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PLAN OF THE MULTICS PROGRAMMERS' MANUAL 
November 30, 1972 

The Multics Programmers* Manual (MPM) is the primary 
reference manual for user and subsystem programming on the 
Multics system. It is divided into three major parts: 

Part I: Introduction to Multics 

Part II: Reference Guide to Multics 

Part Ml: Subsystem Writers' Guide to Multics 



Part I i s an introduction to the properties, concepts, and 
usage of the Multics system. Its four chapters are designed for 
reading continuity rather than for reference or completeness. 
Chapter 1 provides a broad overview. Chapter 2 goes into the 
concepts underlying Multics. Chapter 3 is a tutorial guide to 
the mechanics of using the system, with illustrative examples of 
terminal sessions. Chapter k provides a series of examples of 
programming in the Multics environment. 

Part II is a self-contained comprehensive reference guide to 
the use of the Multics system for most users. In contrast to 
Part 1/ the Reference Guide is intended to document every detail 
and to permit rapid location of desired information, rather than 
to facilitate cover-to-cover reading. 

Part II is organized into ten sections, of which the first 
eight systematically document the overall mechanics, conventions, 
and usage of the system. The last two sections of the Reference 
Guide are alphabetically organized lists of standard Multics 
commands and subroutines, respectively, giving details of the 
calling sequence and the usage of each. 
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Several cross-reference facilities help locate information 
in the Reference Guide: 

. The table of contents, at the front of the manual, 
provides the name of each section and subsection and an 
alphabetically ordered list of command and subroutine 
names. 

. A comprehensive index (of Part li only) lists items by 
subject. 

. Reference Guide sections 1.1 and 2.1 provide lists of 
commands and subroutines, respectively, by functional 
category. 

Part III is a reference guide for subsystem writers. It is 
of interest to compiler writers and writers of sophisticated 
subsystems. It documents user-accessible modules which allow a 
user to bypass standard Multics facilities. The interfaces thus 
documented are a level deeper into the system than those required 
by the casual user. 

Examples of specialized subsystems for which construction 
would require reference to Part III are: 

1) a subsystem which precisely imitates the command environment 
of some system other than Multics (e.g., an imitation of the 
Dartmouth Time-Sharing System); 

2) a subsystem which is intended to enforce restrictions on the 
services available to a set of users (e.g., an APL-only 
subsystem for use in an academic class); 

3) a subsystem which is protecting some kind of information in 
a way not easily expressible with ordinary access control 
lists (e.g., a proprietary linear programming system, or an 
administrative data base system which permits access only to 
program-defined aggregated information such as averages and 
correlations) . 

Each of the three parts of the MPM has its own table of contents 
and is updated separately, by adding and replacing individual 
sections. Each section is separately dated, both on the section 
itself, and in the appropriate table of contents. The title page 
and table of contents are replaced as part of each update, so one 
can quickly determine if his manual is properly up-to-date. The 
Multics on-line "message of the day" or local installation 
bulletins should provide notice of availability of new updates. 
In addition, the Multics command "help mpm" provides on-line 
information about known errors and the latest MPM update level. 
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In addition to this manual, users who will write programs 
for Multics will need a manual giving specific details of the 
language they will use; such manuals are currently available for 
PL/I, FORTRAN, and BASIC. A separate, specialized supplement to 
the MPM is also provided for users of graphic displays. The 
bibliography at the end of Part I, Chapter 1, describes these and 
other references in more detail. 

Multics provides the ability for a local installation to 
develop an i nstal 1 at ion-mai ntai ned or author-maintained library 
of commands and subroutines which are tailored to local needs. 
The installation may also document these facilities in the same 
format as used in the MPM; the user can then interfile these 
locally provided write-ups in the command and subroutine sections 
of his MPM. 

Finally, access to Multics requires authorization. The 
prospective user must negotiate with the administration of his 
local installation for permission to use the system. The 
installation may find it useful to provide the new user with a 
documentation kit describing available documents, telephone 
numbers, operational schedules, consulting services, and other 
local conventions. 
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Section y Commands (03/20/72) 



09/24/73 
01/27/72 
07/29/71 
10/05/73 
08/20/73 

05/17/72 
11/16/73 
11/08/72 
11/07/72 
04/30/73 
02/16/72 
01/03/72 
03/09/73 
02/15/73 
09/22/71 
05/18/73 
02/16/71 
09/28/71 
02/16/71 
10/18/73 
11/13/73 
08/17/73 
08/17/73 
06/24/71 

03/17/72 
06/29/72 
09/26/73 



03/26/73 
03/01/73 

07/24/72 
06/29/72 
03/30/73 
03/30/73 
03/01/73 

07/06/72 
06/29/72 



08/18/71 



abbrev 
addname 

adj ust_bi t_count 
aim 

alm__abs 

and: see Logical Active Functions 

answer 

apl 

arch i ve 
arch i ve_sort 
bas ic 
bas i c_run 
bas ic_sys tern 
b i nd 
cal c 

cance l_abs_reques t 

cancel __daemon__ request 

change_.de faul t_wdi r 

change__er ror_mode 

change_wd i r 

check_i nf o_segs 

cl ose_f ile 

code 

compare 

compare.. asci i 

consol e_output : see file_output 

copy 

create 

created i r 

date: see Date and Time Active Functions 
date_time: see Date and Time Active Functions 
day: see Date and Time Active Functions 
day_name: see Date and Time Active Functions 
debug 
decam 

decode: see code 
del ete 
del ete__di r 
delete_iacl_di r 
del ete_i acl_seg 
del eteacl 

deletecacl: see deleteacl 
del eteforce 
del etename 

directories: see Segment Name Active Functions 
directory: see Segment Name Active Functions 
d i spl ay_component_name 

continued on next page 
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08/17/73 
10/09/73 
02/12/73 
03/19/73 
05/24/72 

03/20/72 



11/20/73 
02/13/73 



10/01/73 
10/01/73 
02/13/73 
02/13/73 

02/12/73 

10/18/73 
02/12/71 



08/22/72 
02/26/73 



02/12/73 
08/18/71 
03/06/73 



02/12/73 
02/13/73 

08/13/73 
07/09/73 
12/09/71 
03/14/72 
05/18/73 
03/30/73 
03/30/73 
10/14/71 
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see Segment Name Active Functions 
Logical Active Functions 



divide: see Arithmetic Active Functions 
do 

dpr i nt 
dpunch 

dump_segment 
edm 

endf i 1 e 
enter 

enterp: see enter 
enter_abs__request 

entry: see Segment Name Active Functions 
equal: see Logical Active Functions 
exec_.com 

exists: see Logical Active Functions 
f i 1 e_putput 

files: see Segment Name Active Functions 
format_l ine: see Character String Active Functions 
f or tran 
for tran_abs 
fs_chname 
get_com_J ine 
get_pathname : 
getquota 
greater: see 
hel p 
hold 

home__dir: see Segment Name Active Functions 
hour: see Date and Time Active Functions 
how__many_users 
ndent 

ndex: see Active Functions 
ndex__set: see Active Functions 
ni tiate 
ocal 1 
omode 

ength: see Character String Active Functions 
ess: see Logical Active Functions 
i ne_l ength 
i nk 

inks: see Segment Name Active Functions 
isp 

i sp_comp i 1 er 
ist 

i s t_abs_reques ts 
i s t_daemon_reques ts 
ist_ iacl_di r 
i st_i ac 1 „seg 
1 ? s t_ref_names 

continued on next page 
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Section 9 Commands (continued) 



see 1 istacl 
see 1 i st 
see list 



see Date and Time Active Functions 



Active Functions 

Active Functions 
see Arithmetic Active Functions 
see Date and Time Active functions 



02/28/73 listacl 

1 i stcacl : 
1 i stnames : 
1 istotals: 
04/05/73 login 
07/05/73 logout 

long_date: 
07/28/72 mail 
05/30/72 make_peruse__text 

max: see Arithmetic 
07/16/73 memo 

min: see Arithmetic 
mi nus : 
mi nu te : 

mod: see Arithmetic Active Functions 
month: see Date and Time Active Functions 
month_name: see Date and Time Active Functions 

04/03/72 move 

06/23/71 movequota 

09/23/70 names 

02/12/71 new_proc 

nond i rector i es : see Segment Name Active Functions 
nonlinks: see Segment Name Active Functions 
nonsegments: see Segment Name Active Functions 
not: see Logical Active Functions 
or: see Logical Active Functions 

05/10/72 page_trace 

path: see Segment Name Active Functions 
pd: see Segment Name Active Functions 

08/18/72 peruse_text 

09/24/73 pll 

09/24/73 pi l_abs 

plus: see Arithmetic Active Functions 
pre__page_of f : see page_trace 
pre_page_on: see page_trace 

02/20/73 print 

07/28/71 print_attach_table 

03/12/73 print_bind_map 

11/11/70 print_dartmouth_l ibrary 

02/16/71 print_defaul t_wdi r 

07/28/71 print_J ink_info 

02/12/71 pr int_J inkage_usage 

02/07/73 pr int_motd 

06/23/71 pr int_search_rules 

02/11/71 print_wdir 

11/05/73 profile 

02/16/73 program_i nterrupt 

continued on next page 
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Commands (continued) 



08/14/73 progress 
11/16/73 qedx 

query: see Question Asking Active Functions 
07/01/71 ready 
07/01/71 ready_off 
06/28/71 ready_on 
07/01/71 release 
02/12/73 rename 
11/13/72 reorder_arch i ve 
09/30/71 repr int_error 
04/27/73 resource_usage 

response: see Question Asking Active Functions 
08/15/72 runoff 
08/22/73 runoff_abs 
03/12/73 safety_sw_off 
03/12/73 safety_sw_pn 

search: see Character String Active Functions 

segments: see Segment Name Active Functions 
02/09/73 set_bi t_count 
02/13/73 set_com_l ine 
11/03/70 set_dartmouth_l ibrary 
03/29/73 set_.iacl_.dir 
03/29/73 set_iacl_seg 
06/30/72 set_search_di rs 
06/25/71 set_sea rch_.ru 1 es 
03/01/73 setacl 

setcacl : see setacl 
11/04/70 sort_.fi le 
04/20/72 start 
03/12/73 status 

string: see Character String Active Functions 
strip: see Segment Name Active Functions 
strip_entry: see Segment Name Active Functions 
substr: see Character String Active Functions 
suffix: see Segment Name Active Functions 

02/12/73 terminate 

termi nate_ref name : see terminate 
terminate_segno: see terminate 
termi nate_s i ngl e_ref name: see terminate 
time: see Date and Time Active Functions 
times: see Arithmetic Active Functions 

08/10/72 trace_stack 

11/14/72 truncate 

unique: see Segment Name Active Functions 

02/15/73 unlink 

user: see User Parameter Active Functions 

04/30/73 v5basic 

verify: see Character String Active Functions 
continued on next page 
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Section 9 Commands (continued) 



09/27/71 walk_subtree 

wd: see Segment Name Active Functions 
02/13/73 where 
08/21/72 who 

year: see Date and Time Active Functions 



Section 10 Subroutines (03/24/72) 



07/05/73 acti ve_fnc_err_ 

08/10/71 adjust_bi t_count_ 

10/08/71 broadcasts 

0 2/ 16/71 change_wd i r_ 

09/ 28/ 73 check_s tar_name_ 

02/16/73 clock. 

11/16/72 com_err_ 

0 2/15/72 command_query_ 

02/25/72 condi tion_ 

08/23/71 convert_bi nary_i nteger_ 

08/10/73 convert_date_to__bi nary_ 

09/16/70 copy_acl_ 

03/15/72 copy_names_ 

03/28/72 copy„seg_ 

06/30/72 cpu_time_and_pagi n&_ 

03/30/73 cu_ 

09/13/73 cv_ad_ 

10/11/72 cv„b i n_ 

05/09/72 cv_dec_ 

09/13/73 cv_dir_acl_ 

08/20/73 cv_dir_mode_ 

03/01/71 cv_f loat_ 

08/20/73 cv_mode_ 

08/18/71 cv_oct_ 

08/20/73 cv_userid_ 

03/08/71 date_time_ 

11/01/71 decode_clock_val ue_ 

0 7/28/71 decode_descr i ptor_ 

08/20/73 decode_entryname_ 

07/14/72 delete. 

09/30/71 di scard__putput_ 

08/16/73 encipher. 

03/08/71 expand_path_ 

11/06/72 file_ 

10/31/73 f ind_condi tion_info_ 

11/30/71 get_defaul t_wdi r_ 

09/28/73 get_equal_name_ 

02/15/73 get _group_id_ 

continued on next page 
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02/28/73 
01/31/73 
02/16/71 
02/12/73 
02/13/73 
03/19/73 
03/20/73 
02/16/73 
02/16/73 
02/13/73 
02/21/73 
03/15/73 
03/U/73 
02/12/73 
02/13/73 
02/12/73 
03/08/73 
02/28/73 
08/2U/71 
02/16/73 
02/27/73 
02/28/73 
03/12/73 
03/12/73 
02/15/73 
02/13/73 
01/17/72 
02/16/72 
02/13/73 
02/15/73 
03/19/73 
03/19/73 
0U/02/73 
03/19/73 



02/20/73 
02/20/73 
02/15/73 
02/20/73 
03/19/73 
03/19/73 
07/11/73 
10/01/73 
09/28/73 
09/17/70 
03/20/73 



get_pd i r_ 
get__process_i d_ 
get_wdi r_ 

hcs__$add_acl__entr i es 
hcs__$add_d i r_acl_entr i es 
hcs_$append_b ranch 
hcs_ $append_branchx 
hcs_$append_l ink 
hcs_$chname_f i 1 e 
hcs_ $chname_seg 
hcs_$del_di r_tree 
hcs_$del ent ry__f i le 
hcs_ $del entry_seg 
hcs_$de1 ete_acl_ent r i es 
hcs_$delete_di r_acl__entr ies 
hcs__$del ete_acl__entr i es 
h c s__$ f s__ge t__mod e 
hcs $fs ,get_path name 
hcs_$f s __get_ref_name 
hcs__$ fs get see p t r 
hcs_$ f s_jnove_f i 1 e 
hcs_$f s_j move_seg 
hcs__$ i ni t iate 
hcs__$ i n i t i ate_coun t 
hcs_$l ist__acl 
hcs__$1 i st__di r__acl 
hcs__$make_j)tr 
hcs_$make_seg 
hcs_$repl ace_acl 
hcs_$ repl ace_d i r_acl 

hcs__$set_bc 
hcs_$set__bc_seg 
hcs_$s ta r_ 
hcs__$status_ 
hcs_$status_long: 
hcs__$status_mi nf : 
hcs__$status_mi ns : 
hcs_$termi nate__f i 1 e 
hcs_$ termi nate_name 
hcs_$ termi nate__noname 
hcs_$ termi nate_seg 
hcs_$ truncate_f i 1 e 
hcs_$ truncate_seg 
ioa_ 
ios_ 

ma t c h_s t a r_n ame_ 

move_names__ 

ns td_ 

continued on next page 
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Section 10 Subroutines (continued) 
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08/27/73 


suf f i xed_name_ 


09/08/71 


syn 


10/01/73 


tape_ 


02/20/73 


term_ 


03/29/71 


t ime r__manager_ 


06/13/72 


total __cpu_t ime_ 


10/03/73 


tw_ 


03/19/73 


un ique_bi ts_ 


02/15/73 


un i que_chars_ 


Olf/13/72 


unpack_system__code_ 


0^/05/73 


user_i nf o_ 


07/09/73 


wr i te_l i st_ 
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IBL MULT ICS COMMAND REPERTOIRE 

The following facilities are the ones considered to be part 
of Multics and are described in this manual. Detailed 
s ngc 1 f ! cat 1 ons on each of the commands mentioned below can be 
found, filed in alphabetical order by command name, in the MPM 
Reference Guide section, Commands. in addition, many commands 
have on-line descriptions that can be obtained with the help 
command. 

The active functions available on Multics are described 
separately, by functional grouping, in several MPM Reference 
Guide write-ups: Alphabetical List of Active Functions / Logical 
Active Functions, Ar i thmat i c Act i ve Functions, Character String 
Active Functions, Segment Name Active Functions, Data and Time 
Active Functions, Question Asking Active Functions, and User 
Paremeter Active Functions. Active functions can be used in a 
command line in the manner described in the MPM Reference Guide 
section, The Command Language, under the heading Active Strings . 

The user should also consult the list of items in the Author 
Maintained and/or Installation Maintained Library at his 
installation, since local language translators and other commands 
can substantially extend the standard command repertoire. 
Documentation of the Author Maintained and/or Installation 
Maintained Library is supplied by the local installation. 

The command repertoire is organized by function into the 
fol lowi ng groups : 

Storage System, Creation and Editing of Segments 

Storage System, Segment Manipulation 

Storage Segment, Directory Manipulation 

Storage System, Access Control 

Storage System, Formatted Output Facilities 

Storage System, Address Space Control 

Language Translators, Compilers, Assemblers and Interpreters 

Object Segment Manipulation 

Debugging and Performance Monitoring 

I/O System Control 

Command Typing and Control 

Communication Among Users 

Account i ng 

Control of Absentee Computations 
Miscellaneous Tools 
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1) Storage System, Creation and Editing of Segments 



adjust_bi t_count 

bas i c_system 
compare_asci i 

create 
edm 
i ndent 

qedx 

sortf i le 



sets bit count of a segment to last 
nonzero character 

editor and runner of BASIC programs 
compares supposedly identical ASCII 
segments, reporting differences 
creates an empty segment 
inexpensive, easy to learn editor 
indents a PL/ I source segment to 
make it more readable 
more sophisticated editor 
sorts ASCII segments line by line 



2) Storage System, Segment Manipulation 



addname 

adjust_bi t_count 

archi ve 

archi ve__sort 

compare 

compare_asci i 

copy 
create 
del ete 

deleteforce 
del etename 

f i 1 e_output 

f s_ chname 
link 

list 

1 i stnames 
1 i stotals 
move 
names 

rename 



adds a name to a segment, directory, 
or link 

sets bit count of a segment to last 

nonzero character 

packs segments together to save 

physical storage breakage 

sorts the contents of an archive 

segment by component segment name 

compares segments word by word, 

reporting differences 

compares supposedly identical ASCII 

segments, reporting differences 

copies a segment 

creates an empty segment 

deletes a segment, but questions if 

segment is read only 

deletes a segment without question 

removes a name from a segment, 

di rectory, or 1 i nk 

directs typewriter output to a 

segment 

an extra powerful rename command 
creates a directory link to another 
segment 

prints directory contents 

moves segment to another directory 
moves or copies names from one 
storage system entry to another 
renames a segment, link, or 
d? rectory 
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reorder_archi ve 

safety_sw_of f 

saf ety_sw_on 

set_bi t_count 
status 



truncate 
unl i nk 

3) Storage System, Directory Manipulation 



rearrages order of an archive 
segment 

turns safety switch off for a 
segment or directory 
turns safety switch on for a 
segment or directory 
sets a given bit count in a segment 
prints everything known about an 
entry in a directory 
used to truncate a segment to a 
specified length 
removes a directory link 



change_def aul t_wdi r 
change_wdi r 
createdi r 
del ete_di r 
1 ist 

1 i stnames 
1 i stotal s ) 
pr i nt_def aul t_wdi r 

pr i ntjwdi r 



sets the default working directory 
changes to a new working directory 
creates a directory 
destroys a directory 

prints directory contents 

prints default working directory 
name 

prints current working directory 
name 



k) Storage System, Access Control 
del ete_i acl_di r 
del ete_iacl_ seg 
del eteacl 
deletecacl 
1 ist_iacl_di r 
1 i st_i acl_seg 



1 i stacl 

1 istcacl 
set_i acl_di r 

set__i acl_seg 



removes an initial ACL for new 
di rector ? es 

removes an initial ACL for new 
segments 

removes an access control list 
(ACL) entry 

removes a common access control 
list (CACL) entry 
prints an Initial ACL for new 
di rector i es 

prints an Initial ACL for new 
segments 

prints an ACL entry 

prints a CACL entry 

adds (or changes) an Initial ACL 

for new directories 

adds (or changes) an Initial ACL 

for new segments 
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setacl 
setcacl 



adds (or changes) an ACL entry 
adds (or changes) a CACL entry 



5) Storage System / Formatted Output Facilities 



dpr i nt 
dpunch 

dump__segment 

mai 1 
memo 

pr i nt 

pr i nt_motd 
runoff 
runoff abs 



adds segment to the high speed line 
printer queue 

adds a segment to the card punch 
queue 

selective octal dump of segment 
contents 

prints or sends mail 

allows users to set reminders 

for later printout 

prints any ASCII segment 

prints the system's message of the 

day 

formats a text segment according 
to internal control words 
invokes the runoff command as an 
absentee job 



6) Storage System / Address Space Control 



change_wdi r 

i ni t i ate 

1 i st_ref_names 

pr i nt__search_rul es 
pr i nt_wdi r 

set_search_di rs ) 
set_ search_rul es J 
termi nate 

where 



controls directory assumed when 
relative path names are given 
adds a segment to the address space 
of a process 

prints all names by which segment 

is known to a process 

prints path of search for missing 
segments 

prints name of current working 
di rectory 

controls path of search for missing 
segments 

removes a segment from process 
address space 

prints full path name of a segment 



7) Language Translators/ Compilers, Assemblers, and Interpreters 



aim 

al m_abs 

apl 

has i c 



assembly language for Multics 
invokes the ALM assembler as an 
absentee job 

invokes the APL interpreter 
translates and optionally runs 
Version 6 BASIC programs 
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bas i c_run 
basi c_system 
fortran 
fortran__abs 

1 isp 

1 i sp_compi 1 er 
pll 

pi l_abs 
qedx 

v2pl l_abs 
v5bas I c 



runs BASIC programs 
editor and runner of BASIC programs 
standard FORTRAN IV compiler 
invokes the FORTRAN compiler as an 
absentee job 

a LISP 1.5 interpreter and compiler 
invokes a LISP compiler 
the Multics PL/I compiler 
invokes the PL/ I compiler as an 
absentee job 

sophisticated editor, with macro 
facilities (a minor interpreter) 
invokes the Version II PL/I 
compiler as an absentee job 
translates and optionally runs 
Version 5 BASIC programs 



8) Object Segment Manipulation 



bi nd 

di spl ay_component_name 
pr i nt_bi nd_map 
pr i nt_l i nk_j nf o 



segments 



packs two or more object 
into a single segment 
prints name of bound component, 
gives offset 

prints information about a bound 
segment 

prints list of entries and outbound 
links of an object segment 



9) Debugging and Performance Monitoring 



change_error_ mode 
debug 

dump_segment 
hold 

how.jnany^.users 
page_trace 

pr i nt_l i nkage_usage 
prof i 1 e 



progress 



adjusts length and contents of status 
messages 

symbolic source language debugger 
selective octal dump of segment 
contents 

saves the stack for debugging or 
later restart 

tells how many users are logged in 
prints list of pages recently 
demanded 

prints map of all current linkage 
prints information about execution 

of individual statement within a 
program 

prints information about the progress 
of a command as it is being executed 
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ready 

ready_pf f 

ready_on 
repr i nt_ error 

trace_stack 
where 

10) I/O System Control 



prints a summary line of CPU time 

and paging usage 

suppresses the ready line 

following commands 

restores the ready line 

allows retyping of earlier status 

messages 

prints stack history 

prints full path name of a segment 



cancel_daemon__request cancels a previosuly submitted 

daemon request 

closes open FORTRAN and PL/1 files 
restores typewriter output to the 
typewr i ter 

adds a segment to the high speed 
printer queue 

adds a segment to the card punch 
queue 

directs typewriter output to a 
segment 

allows direct calls to I/O system 
entries 

sets typewriter character conversion 
modes 

sets typewriter carriage length 
prints list of daemon requests 
currently queued 

prints list of current I/O system 
stream attachments 



close_f i 1 e 
consol e_output 

dpr i nt 

dpunch 

f i 1 e_output 

iocal 1 

iomode 

1 i ne_l ength 

1 ? st__daemon_requests 



pr i nt_attach_table 
11) Command Typing and Control 



abbrev 

answer 
do 

enter 
exec_com 

get_com_l i ne ) 
set_com_l • ne J 



allows user-specified abbreviations 
for command lines or parts of 
command lines 

answers questions normally asked 
of the user 

executes a command line with 

arguments inserted 

enters an anonymous user into the 

system 

allows a segment to be treated as 
a list of commands to be executed 
adjusts size of command line 
buffers 
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hold 

login 

logout 

new_proc 

program_i nterrupt 

rel ease 
start 

wal k_subtree 



saves the stack for debugging 
following an accident 
enters user into the system 
exits user from the system 
creates a new process wi th a 
fresh address space 
signals a condition following an 
acci dent 

releases a saved stack 

restarts a computation following 

a quit or unexpected signal 

repeats a command in all directories 

below a given directory 



12) Communication Among Users 



change__wdi r 
check_j nf o__segs 

hel p 
1 ink 

mai 1 

make__peruse_text 
peruse_text 
set_search_di rs 

unl ? nk 

where 

who 

13) Accounting 
getquota 
movequota 
resource_usage 



changes base of operation to 

another directory 

checks information (and other) 

segments for changes 

prints special information segments 

inserts a directory link to 

another segment 

sends an ASCII message to another 
user 

prepares segments for use by 
peruse_text 

selectively prints structural 

information segments 

sets path of search for missing 

segments 

removes a directory link 
prints full path name of a segment 
prints list of users currently 
logged in 



prints secondary storage quota 
and usage 

moves secondary storage quota to 
another directory 
prints resource consumption for 
the month 
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lk) Control of Absentee Computations 



alm_abs 

cancel _abs__reques t 

enter_abs_request 

fort ran__abs 

1 i st_ abs_reques t 

pi l_abs 

runof f_abs 

who 

15) Miscellaneous Tools 

arch i ve 

archi ve_sor t 

cal c 
code 

decam 
decode 

pr i n t_mo t d 
reorder__arch i ve 
who 



invokes the ALM assembler as an 
absentee job 

cancels a previously submitted 
absentee job request 
adds a request to the absentee 
job queue 

invokes the FORTRAN compiler as an 
absentee job 

prints list of absentee job 

requests currently queued 

invokes the Version I PL/I compiler 

as an absentee job 

invokes the runoff command as an 

absentee job 

prints list of absentee jobs 
currently logged in 



packs several segments together 
to save physical storage breakage 
sorts the contents of an archive 
segment by component segment name 
a desk calculator 

enciphers a segment, given a coding 
key 

another desk calculator 

deciphers a segment/ given the proper 

coding key , c 

prints the system's message of the 

day 

rearranges order of an archive 
segment 

prints list of users currently 
logged in 
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The first step in using Multics is to establish a connection 
between the user's terminal and the system / as described in the 
MPM Introduction/ Chapter 3/ under The Mechanics of Terminal 
Usage . After the user has established that connection, Multics 
responds : 

Multics 20.6; MIT/ Cambridge/ Mass. 

Load = 16.0 out of hO.O units; users = 15 

where the system/ the site, the number of units and users 
currently logged \n, and the maximum number of units currently 
permitted are, of course/ variable. 

Logging in 

Once the user has obtained the "Load =" message (and if he 
still wishes to log in)/ he should type: 

login person -project- -control_arguments- 

If the project is omitted/ the user's default project ID is used. 
(See the write-up of the login command for more information.) 
Multics responds: 

Password: 

The terminal prepares for the user's typing of his password by 
x'ing out the line following the password request. The user then 
types his password (eight characters or less); e.g./ 

qwertyui 

At this point/ Multics prints one of the fol lowi ng messages : 

1) person project logged in: date time from type terminal "x" 

There is a short interval during which the process is 
created for the user, followed by the printing of the 
message of the day, followed by a ready message (see Ready 
Messages below). If the user's password has been given 
incorrectly since its last correct use, a message to that 
effect is also printed. 
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2) System full. Please try again later. 

Acceding to the user's login request would cause the number 

of logged in users to exceed the current maximum. (Note 

that certain users have privileges such that they can log in 
despite the current maximum setting.) 

3) Load control group full. Please try again later. 

The user f s load control group has its maximum number of 
users already logged in. 

k) Incorrect login word. 

The user has not specified a recognizable login request. 

5) login: illegal argument "xxx". 

The user has specified an illegal parameter in his login 
request 1 ine. 

6) Home directory missing. 

The user's home directory does not exist and cannot be 
created. 

7) You are subject to preemption. 

This message is printed in conjunction with message 1 
(above). It indicates that the user has been assigned 

secondary status and can be preempted if the system becomes 
full and a primary user from any load control group logs in. 

8) You are protected from preemption until hhmm. 

This message is printed in conjunction with message 1 
(above). It indicates that the user has been assigned 
primary status and cannot be preempted until the time given. 
Once this time arrives/ the user retains primary status 
until another user from his load control group attempts to 
log in and finds the load control group full. The first 
user can then be demoted to secondary status or preempted, 
depending on whether or not the system is full. 
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9) Special session in progress. 

A new version of Multics is being tested, or certain repair 
or administrative work is in progress which requires that 
users be temporarily restricted from accessing the system. 

10) Login incorrect. 

Some item in the system's verification of the user's attempt 
to access Multics was incorrect. I.e., the user's name 
or project was not registered (or was mistyped) or the 
password was incorrectly typed. 

11) person. proj ect already logged in from type terminal "x" 

The user-project combination is already using Multics. A 
message notifying the already logged in user of the current 
login attempt is printed at his terminal. 

If a user does not complete his login within a few minutes, 
his terminal hangs up. 

User ' s Process Parameters 

Several attributes of the user's process can be controlled 
by the user's project administrator. The project administrator 
can, in turn, allow the user to override some of these attributes 
by specifying control arguments in his login or enter line. (See 
the login and enter command write-ups.) The variable attributes 
and their values for most users are: 

1) home directory 

The project administrator can specify the path name of the 
user's home directory. The project administrator can also 
permit the user to override this specification by use of the 
-home_dir control argument to the login or enter commands. 
The usual value for a user's home directory path name is: 

>user_di r_di r>proj ect > person 

and if the path name has this form, and the directory does 
not exist, the login or enter commands attempt to create the 
d i rectory. 
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2) process overseer 

The user's process overseer is the procedure which is called 
to initialize the user environment when a process is 
created. The project administrator can specify the path 
name of this procedure. The project administrator can also 
allow the user to override this specification by use of the 
-process_overseer control argument to the login or enter 
commands. The usual value for a user's process overseer is: 

process_overseer_ 

If the user's process overseer cannot be located, the user 
process cannot be initialized. 

3) initial and maximum r i ng number 

The project administrator can specify the initial protection 
ring in which the user process begins execution, and the 
maximum ring in which the user process can execute, within 
limits set by the system administration. This specification 
cannot be overridden by the user. The usual values for 
these parameters are: 

initial ring: k 
maximum ring: 7 

k) preemption protect ion t ime 

The project administrator can specify the minimum amount of 
time that a user can hold primary status, within limits set 
by the system administration. The user cannot override this 
specification. The usual value for most users for this 
parameter is kS hours. 

5) password 

The user can change his password by use of the 

-change^ password control argument to the login command. The 

command asks first for the current password to verify the 

identity of the user, then for the new password. On 
subsequent logins, the new password is required. 

6) default project 

The user can change his default project (for subsequent 
logins) to the project specified in the current login 
command 1 i ne . 
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7) attributes 

A number of one-bit flags which determine user privileges 
are referred to as the user attributes. The system 
administrator can allow project administrators to set 
certain of them for users on a project/ and some of them 
can be overridden by the user. The attribute flags include: 

a) brief 



If on , the user does not receive messages associated with 
a successful login. If the user is using the standard 
process overseer/ the message of the day is not printed. 
The project administrator can force this attribute to be 
on, or the user can set it to op. by use of the -brief 
control argument to the login or enter commands. 



b) nostartup 



If on, the user can specify the -no_start__up control 
argument to the login or enter commands/ and cause his 
start_ up.ec to be bypassed. (See Start Up below.) Most 
users have this attribute set to on . 



c) v_process_overseer 



If on , the user can override the process overseer 

specification by use of the -process_overseer control 

argument to the login or enter commands. If off , the 

control argument has no effect. Most users have this 
attribute set to on. 

d ) v_home_d i r 

If ojQ/ the user can override the home directory 
specification by use of the -home_dir control argument to 
the login or enter commands. If off , the control 
argument has no effect. Most users have this attribute 
set to o_n. 



e) preempting 

If on/ the user can preempt other primary users in his 
load control group whose grace has expired. The user can 
cause this attribute to be set to off by use of the 
-no_preempt control argument to the login or enter 
commands . 
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f) guaranteed. logi n 

If on, the user is logged in / if at all possible, if he 
also specifies the -force control argument to the login 
or enter commands. This attribute flag is set to on only 
for system users for emergency repair applications. 



g) multip 

If on, the user can be logged in more than once 
simultaneously. Only system daemon users have this 
attr i bute. 



h) nobump 



If on, the user cannot be bumped by name by the system 
operator. Only system daemon users have this attribute. 



I) nolist 



If on , the user is not listed on the output of the who 
command. This attribute is not normally given to any 
user. 

j) no_primary 

If on , the user cannot have primary status. 

k) no_secondary 



If on , the user cannot have secondary status. 

Start U£ 

Upon beginning execution in a new process/ a user might 
desire his process to perform certain actions before coming to 
command level. In order to do this, the user can create an 
exec_ com segment (see the MPM write-up of the exec_ com command) 
that contains commands which are to be executed before his 
process attempts to read from his terminal. This segment must be 
named start_up.ec and must reside in the user's initial working 
di rectory . 
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If the segment start_up.ec exists in the user's initial 
working directory, the printing of the message of the day is 
suppressed. In addition, the command "exec_ com start_up 
creationtype process type" is executed as a command during process 
initialization. If the process is being created because the user 
has logged in, creationtype is the string "login". If the 
process is being created because of a new_proc command or a 
process termination, creationtype is the string "new_proc". If 
the process being created is interactive, then processtype is the 
string "interactive". If the process being created is an 
absentee process, processtype is the string "absentee". 

This feature allows users to initialize their processes as 
they see fit. Some uses of this feature might be to suppress 
ready messages or change the search rules. 

R£dj& Usages 

The ready message is a printed response designed to provide 
timing information for the user. It is of the form 

r time cpu mu pf 

and is printed after every command or sequence of commands, and 

after a quit condition, time is the current time of day (24-hour 

notation), cpu is the amount of processor time charged to the 

process (in seconds, to the nearest millisecond), mu is the 

memory usage and pf is the number of page faults. The cpu, mu 

and pf figures are the values since the last calculation or, in 

the case of the first ready message for a. new. prpcess, the time, 
memory usage, and page faults required to initialize the process. 

Speci al Subsystem Use 

Some projects may wish to arrange for a special process 
overseer procedure to be called when a user logs in, instead of 
the standard Multics procedure, in order to modify the system's 
appearance to the terminal user. A project administrator can 
specify a special process overseer for any user on his project. 
The MPM Subsystem Writers' Guide write-up for the 
process_overseer_ subroutine contains further information. 
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Anonymous Users 

For some applications (like short courses)/ it is desirable 
to allow unregistered persons to log in as users of a particular 
project. Multics allows a project to register a special/ 
anonymous user. Users who log in under this identity are given 
the access name anonymous. project. a, and any number of these 
users can log in at once. When used in conjunction with the 
special process overseer control argument described above, this 
facility allows a subsystem to simulate other time-sharing 
systems under Multics. 

There are two varieties of anonymous user registrations and 
two corresponding login procedures. For anonymous users who have 
a password/ the user types 

enterp person project -control^ arguments- 

instead of the login line described above. No default project ID 
is possible. The system then asks 

Password : 

and continues with the normal login sequence. For anonymous 
users with no password (usually those with a special process 
overseer which checks for a password)/ the user types 

enter person project -control_arguments- 

The system skips requesting a password and goes directly to the 

logged In message. For both cases, the user's name as given on 
the login line is available to a special process overseer for any 
checks It wishes to make. (See the MPM command write-up for 
enter . ) 

Lofifl'Pfi Oul 

When the user has finished his current terminal activity/ he 
issues the command 

logout 

Multics disconnects the user's telephone line after printing 

person project logged out date time 
CPU usage ss sec, memory usage uu units 
hangup 
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Emergency logput 

When a scheduled shutdown or system emergency occurs, the 
user may see the following message appear on his terminal: 

Automatic logout 

person project logged out date time 
CPU usage ss sec, memory usage uu units 
hangup 

followed by the telephone line disconnection as for a normal 
logout command. If possible, a warning message is printed a few 
minutes before the automatic logout message appears. 

Unschedul ed Pi sconnect ions 

If, for some reason, the user's telephone connection to 
Multics is broken, the Multics system recognizes this event and 
issues an automatic logout for the user (without printing on the 
user's terminal, needless to say). If he has more work to 
accomplish, he should dial into Multics again and attempt the 
standard login sequence. 

Logout for I nact i vi ty 

If a user is inactive (that is, his process remains blocked) 
for more than the installation-specified maximum time limit, 
Multics logs the user out with the following message: 

Maximum inactive time exceeded 
person project logged out date time 
CPU usage ss sec, memory usage uu units 
hangup 

Termi nal Swi tch Setti ngs 

Switches must be set as indicated below for interaction with 
the computer. 

27U1: LCL-COM switch on COM . 

INHIBIT AUTO EOT switch (if present) on. 

Power swi tch on . 

The quit button is marked ATTN. 

The end of line key is marked RETURN. 
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Datel: LOCAL-REMOTE switch on REMOTE . 

EOT- I NH switch on INH . 

Power swi tch on . 

The quit button is marked ATTN. 

The end of line key is marked RETURN. 



1050: System switch on Attend . 

Printer 1 switch on SendRec . 
Keyboard switch on . 
System switch up. 
Test swi tch off . 
Power swi tch on . 

Line Control Switch (located inside rear 
pedestal door) on . 

The quit button is marked RESET LINE. 
The end of line key is marked RETURN. 



37: No switches are accessible. Power is turned on 

by the DATA button. 

The quit button is marked INTERRUPT. 

The end of line key is marked LINE SPACE. 

38: Li ne button on 

Both the CR and LF buttons must be pressed 
sequentially to generate the equivalent of a 
Multics new line (carriage return_line freed). 
Carriage return should be typed first, then 
1 i ne feed. 

The quit button may be unmarked — it is the 
second button from the bottom in the right hand 
colomn of five buttons. 

35: ON-LINE/OFF-LINE switch on ON-LINE . 

HALF DUPLEX/FULL DUPLEX switch on FULL DUPLEX . 

The quit button is marked BREAK. 

The end of line key is marked LINE FEED. 



33: ON-LINE/OFF-LINE switch on ON-LINE . 

HALF DUPLEX/FULL DUPLEX switch on FULL DUPLEX . 

The quit button is marked BREAK. 

The end of line key is marked LINE FEED. 

ARDS: Power switch (on back) oji. 

Press RESET button before dialing. 
The quit button is marked: 

a) when in read mode, the CONT and Q buttons 
pressed at the same time; 

b) when in write mode/ the WAIT button. 
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The end of line key is marked LF. 

Terminet 300: The ON LINE and READY buttons should be lit. 

The INTERRUPT button should light up when 

the quit button is hit. 

Transparency switch off . 

Inhibit switch on Norm . 

Rate switch set to 15 . 

Line Feed switch on 1. 

Auto L.F. switch on . 

The quit button is marked INTERRUPT. 

The end of line key is marked RETURN. 

Execuport 300: The PWR switch (on back panel) should be o_n. 

Mode switch on LINE . 

DUPLEX switch on HALF . (Can be set to 

FULL to suppress printing of the password 

only. ) 

CHAR/SEC switch on JJL. (Should be set to 

10 if dialed into a 110 baud line.) 

PARITY switch on EVEN . 

QSL swi tch on LOWER . 

The quit button is marked BRK. 

Both the LF and CR buttons must be pressed 

sequentially to generate the equivalent of a 

Multics "new line" (carriage return-line feed). 

Either button can be pressed first. 

Trendata 1000: Power switch QH (POWER indicator light turns 

on) . 

COMM button lighted (press switch to enter or 
leave communication mode). 

LOCAL button unlighted (press switch to enter 

or leave local mode). 

The quit button is marked ATTN. 

The PROCEED light indicates that the keyboard 

is unlocked. 

The ERROR CHECK light indicates that a 
character cannot be printed. 

The UNLOCK button can be depressed to free the 
keyboard and turn on the PROCEED light. 
The end of line key is marked RETURN. 
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Tektronix 1*013: 



Power switch (under the 
indicator light turn on). 
LINE/LOCAL switch to the LINE 
TRANSMIT AND RECEIVE baud 
pedestal) set to 1200. 
FULL DUPLEX/HALF 
pedestal ) set to 
CARRIAGE RETURN 
set to CR/LF. 

The quit button is marked BREAK. 
The end of line key is marked LF. 



keyboard) pji (POWER 



pos i t i on. 
rates (on 



back of 



of 



DUPLEX switch (on back 
HALF DUPLEX, SUPERVISOR, 
switch (on back of pedestal) 



Teleterm 1030: Power switch on . 
(Multics version) Duplex switch on half. 

Parity switches set to on. and even . 

SPEED set to 10, 15, or 30 depending 

a 110 baud, 150 baud, or 300 baud 

number was dialed. 



on whether 
tel ephone 



Note that when using Multics via a data network, the above switch 
settings may be superseded by local host conventions. 



JHQjfce. 

See also the MPM Reference Guide section. Typing 

Conventions, for information on keyboard input and output 

conventions. In general, the conventions described there apply 

to logging in and out as well as all other typing. 
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I T F 1 ft U V LIN I i uiSib 

Three categories of typing conventions are dealt with in 
this section: canonical form / erase and kill characters, and 
escape characters. Quits, which might reasonably be considered a 
typing convention, are discussed elsewhere. The button that can 
be pressed to cause a quit condition to be signalled is listed 
for each terminal type under Termi na 1 Swi ten Sett i ngs in the MPM 
Reference Guide section, Protocol for Logging In. Handling of 
the condition is discussed under the quit condition in the MPM 
Reference Guide section, List of System Conditions and Default 
Handl ers . 

Canoni ca 1 Form 

The concept of a canonical representation of a printed line 
image described here has been used in at least two character 
oriented systems: in TYPSET on the IBM 709U (as suggested by Earl 
Van Horn), and in the TITAN operating system on the ATLAS 
computer . 

Characters are intended ultimately for human communication, 
and conventions about a printed line must be made with this in 
mind. A character stream is a representation of printed lines. 
In general, there are many possible character streams that 
represent the same line. In particular, on input, a typist can 
produce the same printed line twice with different sets of key 
strokes. For example, the line 

start Ida alpha, k get first result. 

could have been typed with either .spaces. or hor i zonta 1 . tabs 
separating the fields; one cannot tell by Tooking at the printed 
image. Since it is not possible for the individual to 
distinguish between several ways of typing a printed 
representation, no program should deliberately attempt to do so 
ei ther . 

For example, a program should be able to compare easily two 
character streams to see if they are the same, in the sense that 
they produce the same printed image. It follows that all 
character input to Multics must be converted into a standard 
( canoni cal ) form. Similarly, all programs producing character 
output, including editors, must produce the canonical form of 
output stream. 

Effectively, of all possible ASCII character strings, only 
certain of those strings are ever found within Multics. All of 
those strings that produce the equivalent printed effect on a 
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typewriter terminal are represented within Multics as one string/ 
the canonical form for the printed image. 

No restriction has been placed on the individual at his 
terminal; he is free to type a noncanonical character stream. 
This stream is automatically converted to the canonical form 
before it reaches his program. For the user who wants his 
program to receive raw or partially processed input from his 
terminal/ the following escape mechanism is provided. The tw_ 
outer module (see the MPM write-up for the tw_ subroutine) 
supports the following applicable modes below through the 
changemode cal 1 : 

-•can no canonical ization of overstrikes. 

-'esc no canonical ization of escape characters. 

-•erkl no erase and kill processing. 

rawi the specified data is read from the terminal without 

any conversion or processing. This includes shift 
characters and undifferentiated upper and lower 
case characters. 

Similarly/ an I/O System Interface Module ( I OS I M) is free to 
rework a canonical stream on output into a different form if/ for 
example/ the different form happens to print more rapidly or 
reliably on the device. 

We assume that every I OS I M is able to determine 

unambiguously what precise physical motion of the device 
corresponds to the actual character stream coming from or going 
to it. In particular/ the IOSIM must know the location of 
physical tab settings. This requirement places a constraint on 
devices with movable tab stops. When the tab stops are moved/ 
the IOSIM must be informed of the new settings. Standard Multics 
software assumes that tab stops are at character positions 11/ 
21/ 31/ 1*1/ etc. 

The current Multics canonical form does not meet all of the 
objectives of the above discussion: it represents a compromise 
between whose objectives and that of convenience of typing 
aligned tabular information/ which requires an ambiguous 
interpretation of the tab character. The following three 
statements describe the current Multics canonical form. 

1) A message consists of strings of character positions 
separated by carriage motion. 
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2) Carriage motion consists of new line, tab, or space 
characters . 

3) Character positions consist of a single graphic or an 
overstruck graphic. A character position with overstrikes 
contains the numerically (in ASCII sequence) smallest 
graphic, a backspace character, the next larger graphic, etc. 

Thus, for the most part, the canonical stream differs little from 
the raw input stream it was derived from. 

Fxamol es of Canoni ca 1 Form 

Several illustrations of canonical form are shown below. 
The examples do not attempt to cover every conceivable variation 
or combination of characters, but, rather, illustrate the intent 
and the method. (In the examples, assume that the typist's 
terminal has horizontal tab stops set at 11, 21, 31, etc.) 

Typist: This is ordinary text.<NL> 

Printed line: This is ordinary text. 
Canonical form: This is ordinary text. <NL> 

For the case of simple, straight line input, the canonical form 
reduces to the original key strokes of the typist. Most input 
probably falls into this category. 

Typist: Here f ul 1<BS><BSXBSXBS> means that<NL> 

Printed line: Here f ul 1 means that 

Canonical form: Here _<BS>f_<BS>u_<BS>l_<BS>l means that<NL> 

This is probably the most common example of canonical conversion, 
to insure that overstruck graphics are stored in a standard 
pattern . 

Typist: We see no prob <BS>lem<CR> <NL> 

Printed line: We see no problem 
Canonical form: _<bs>W_<bs>e see no problem 

(Recall that the carriage return (CR) does not produce a line 
feed.) The most important property of the canonical form is that 
meanderlngs of the typist within a line are irrelevant. The 
typist need merely concern himself with the printed image. 
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Erase and K? 1 1 Characters 

Experience has shown that even with sophisticated editor 
programs available/ two minimal editing conventions at the 
earliest possible level are very useful for human input to a 
computer system. These two conventions give the typist two 
editing capabilities at the instant he is typing: 

1) Ability to delete the last character or characters typed. 

2) Ability to delete all of the current line typed up to this 
poi nt . 

(More complex editing capabilities are also available, but they 
fall in the domain of editing programs that can work with lines 
previously typed as well as the current input stream.) By 
framing these two editing conventions in the language of the 
canonical form, it is possible to preserve the ability to 
interpret unambiguously a typed line image despite the fact that 
editing was required. 

The first editing convention is that one graphic, the number 
sign (#), is reserved as the erase character. When this 
character appears as the only graphic in a print position, it 
erases itself and the contents of the previous print position. 
When it is not the only graphic in a print position, it erases 
the print position in which it appears. If the erase character 
follows simple carriage motion, the carriage motion is erased. 
Several successive erase characters erase an equal number of 
print positions or simple carriage motions. Since erase 
processing occurs after the transformation to canonical form, 
there is no ambiguity as to which print position has been erased; 
the printed line image is always the guide. Whenever a print 
position is erased, any carriage motion on the two sides of the 
erased print position is combined into a single carriage motion. 

The second editing convention reserves another graphic, the 
commercial at sign (@), as the ki 1 1 character. When this 
character appears as the only graphic in a print position, the 
contents of that line up to and including the kill character are 
discarded. Again, since the kill processing occurs after the 
conversion to canonical form, there can be no ambiguity about 
which characters have been discarded. By convention, an 
overstruck erase character is processed before a kill character, 
and a kill character is processed before a non-overs truck erase 
character. Therefore, a kill character can only be erased by an 
overstruck erase character. 
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Exampl es of Erase and Kill Process i ng 

Typist: abcx#de<SPXBS>f zz##g<NL> 

Printed line: abcx#def zz##g 
Canonical form: abcx#def zz##g<NL> 
Final input: abcdef g<NL> 

This represents the primary use of the erase character, 
correcting typing errors the moment they are noted. Note that 
the erroneous space between e and f was not erased, it was 
undone. 

Typist: Thi s@The of f <BSXBSXBS> ##n<BS>__<SP>state<NL> 

Printed line: This@The of f ##n state 

Canonical form: This@The _<BS>o_<BS>f_<BS>f ##_<BS>n state<NL> 
Final input: The _<BS>o_<BS>n state<NL> 
Printed appearance of final form: The on state 

Escape Characters 

Contemporary terminal equipment often is not capable of 

representing all 128 of the ASCII code values. To keep full 

generality and flexibility in the future, standard software 

escape conventions are used for all terminal devices. On devices 

that have the revised ASCII set, the use of the escape mechanism 

is normally unnecessary. Each class of terminal device has a 

particular character assigned as the software escape character. 

When this character occurs in an input (or output) string to (or 

from) a terminal it always gives a special interpretation to the 

next one or more characters. The standard escape character is 
the left slant; this means that to input the code for it, an 

escape convention has to be used. Therefore, the left slant 

should be avoided in all Multics software. (It should be noted 

that the two standard erase characters, # and @, should also be 

avoided ?n all software.) 

For simplicity, universal escape conventions have been 
established that are uniform over several terminal classes. For 
full flexibility, there is a mechanism for representing any 
arbitrary octal code in a character string. The universal escape 
conventions are: 

\dld2d3 for the octal code dl d2 d3 where dl, d2, d3 are 
from zero to seven. \d2d3 is equivalent to \dld2d3 if dl is 
zero. \d3 is equivalent to \dld2d3 if dl and d2 are zero. 
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\<NL> for a local (i.e./ concealed) use of the new line 
character that does not go into the computer-stored string on 
input and that is not in the computer-stored string on output. 

\# for placing an erase character into the input string. 

\@ for placing a kill character into the input string. 

\\ for placing a left slant character into the input string. 

One additional stylistic convention holds for all terminals: 
the solid vertical bar (|) and the broken vertical bar (j) are 
equivalent representations of the graphic for ASCII code 17k, 

IBM 1050 and 27kl Terminals 

Each type ball used requires a different set of escape 
conventions. 

EBCDIC Type B all (9£I) and EBCpiC Keypunches 

The following non-ASCII EBCDIC graphics are considered to be 
stylized versions of ASCII characters: 

£ (cent sign) for \ (left slant/ software escape) 
1 (apostrophe) for ' (acute accent) 
(negation) for * (circumflex) 

In addition to the four universal escape conventions/ the 
following are available for convenience. 

for x (grave accent) 

£< for C (left bracket) 

£> for 3 (right bracket) 

£( for { ( left brace) 

O for } (right brace) 

£t for - (tilde) 

There are no currently implemented escapes for IBM 029 

keypunches with EBCDIC codes. 

In the case of keypunches/ an end-of-card automatically 
generates a new line character. It is also convenient for input 
to have: 

<!:* for "skip reading the remainder of this card without 

the new line character" 
£/ for "new line and skip reading the remainder of this 
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<!: + 
CH 



card" 

for "new line and keep reading this card 
for horizontal tab 



ii 



Note that one can use the multiple punch codes described in the 
MPM Reference Guide section, Punched Card Codes, when at an 029 
keypunch instead of the above escape conventions. The two sets 
of conventions (escape and multiple punch) are interchangeable, 
even in the same card deck. 

Model 31 ajid 15 Teletypes 

Because these models do not have both upper and lower case, 
the following typing conventions are necessary to enable users to 
input the full ASCII character set: 

1) The keys for letters A through Z input lower case letters a 
through z, unless preceded by the escape character \ (left 
slant). The left slant is shift-L on the keyboard, although 
it does not show on all keyboards. For example to input 
"Smith. ABC", type " \Smi th.\A\B\C" . 

2) Numbers and punctuation map into themselves when possible. 
The underscore (_) is represented by the back arrow («-) . The 
circumflex (~) is represented by the up arrow (r). The acute 
accent ( / ) is represented by the apostrophe ( ! ). 

3) The following other correspondences exist: 

Character type in octal 

backspace \- 010 



In normal I/O mode, characters are output according to these same 
rules. In edited I/O mode, the output drops the left slant and 
becomes much tidier, but ambiguous. 

Model 37 and 38 Teletypes 

There are no additional escape conventions for the model 37 
and 38 teletypes since they use the full ASCII character set. 



grave accent ( x ) 
left brace ( { ) 
vertical line (!) 
right brace ( } ) 
tilde (~ ) 



\( 
\! 
\) 



173 
17U 
175 
176 
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Execuport 100 

The following non-ASCII characters on the keyboard are 
considered to be stylized versions of ASCII characters: 

<- (back arrow) for _ (underscore) 
f (up arrow) for a (circumflex) 
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THE COMMAND LANGUAGE 

A system command is a program furnished by the system that 
performs some general/ canned function for a user. Such programs 
are called commands because they carry out users' orders to the 
system (renaming a segment/ compiling a program/ etc.). In 
MulticS/ system commands are not a special class of program. Any 
user program that takes character strings as arguments can be 
invoked as a command. (See the MPM Reference Guide section/ The 
Multics Programming Environment.) The command processor can be 
viewed as simply a mechanism for invoking programs by name. 

It is clearly necessary to establish some conventions for 
the syntax of a command line. (A command line is defined as the 
sum of a command name plus any arguments to be passed on to the 
command when it is invoked. Note that/ in Multics, the general 
rule is for system commands to accept arguments at invocation and 
not to acquire them by interrogation of the user during 
execution.) It should also be clear that it is not usually 
desirable to declare that the syntax be identical to the 
subroutine call of some particular programming language/ since 
the engineering of human interfaces is different from that of 
subroutines. The conventions developed here are chosen for 
simplicity in the basic case, and for functional flexibility in 
the nonbasic cases. That is/ various services such as nesting 
and iteration of commands are furnished/ and the command language 
syntax allows these features to be specified by means of certain 
special delimiters in the command line; but if the services are 
not desired/ the user need only type his commands according to 
the format discussed below under S imp! e Commands . For that 
matter, the command system is avoidable; some subsystems under 

Multics may choose to interact with their users in their own 
fashion/ with their own conventions. Most users, however/ deal 
with Multics directly through the command system. 

Context 

After successfully logging in to the system, the user is 
said to be at command level. Then and thereafter, from the point 
of view of the user, command level is the time after a ready 
message, at which point the system is available for new commands. 
That is, when a command has finished executing, it returns to the 
command processor (which called it in the first place)/ and the 
command processor prints a message on the user's terminal 
informing him that the system is ready for further orders. When 
the user is at command level/ he issues commands in the syntax of 
the command language described herein. Note that because Multics 
typewriter input allows read-ahead/ the user does not have to 
wait for a ready message before typing another command line. He 
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can, however, be interrupted in the middle of typing a line by 
the ready message. If this occurs, that line is lost and must be 
retyped. The typing of ready messages can be turned off and on 
using the commands ready_off and ready_pn (see the MPM command 
wr i te-ups) . 

Simpl e Commands 

A command line specifies a function to perform plus, if 
appropriate, the arguments with which the function is to operate. 
Each command line element is currently treated as a character 
string. That is, individual commands are called with character 
string arguments, there currently being no conversion by the 
system of, say, numeric characters to binary representation. 

There are two basic elements of a command line. The first 
is the command name. This is essentially a reference name, i.e., 
a (procedure) segment name, and, if appropriate, an entry point 
name. The command processor uses the user's search rules (see 
the MPM Reference Guide section, The System Libraries and Search 
Rules) to find the program whose name is the command name. 
However, the reference name can be preceded by a storage system 
hierarchy location specification; that is, it can be a path 
name. In this case, the search rules are superseded and the path 
name is used to find the program. Subsequent unqualified 
references to the same reference name are treated as if the path 
name were present (see example below). The second basic element 
is the argument. This is simply a character string designating, 
for instance, a segment. Depending on the particular command in 
question, there can be from zero to an arbitrary number of 

arguments. The element delimiter (or separator) in a command 
line is the space (or blank). The terminator of a command line 
can be either the semicolon (;) or the new line character. Note 
that more than one command can be issued on the same line of 
console input by using the semicolon between commands. 

The general form of the simple command is 

comma nd_ name argl. ... argn. 

with each element separated from the preceding one by one or more 
spaces. For example, the rename command takes arguments in 
pairs; the first is the current path name of the segment to be 
renamed and the second is the desired new entry name. Thus, 

rename square_root sqrt 
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causes the command processor to search for and invoke a procedure 
named rename at entry point rename with the character strings 
n square = root M and "sqrt 11 as arguments. There is no difference 
between invoking a command from the console and calling it in a 
procedure. For example/ typing the command line "rename 
square_root sqrt" is equivalent to executing the following PL/I 
program: 

x: proc; 

call rename ("square_root", "sqrt"); 
end x; 

As another example, suppose that one knows that an 
experimental version of the rename command resides in the 
directory >Smith_dir. If one types: 

>Smi th_di r>rename square_root sqrt 

then the experimental version is invoked. That is, the program 
rename in the directory >Smith_dir is invoked with the character 
string arguments "square_root ,f and "sqrt". Subsequent 
unqualified references to rename invoke the one in >Smith_dir. 
In like manner, any program in the storage system hierarchy can 
be invoked. 

iteration 

Sometimes the user wishes to repeat a command with one or 
more elements changed. The iteration facility of the command 

language is provided for economy of typing.. The , iteration, set 
consists of one or more elements enclosed by parentheses 
(parentheses are reserved characters). Each element of the set, 
in turn, replaces the entire set ir the command line. For 
exampl e, 

print (a b c).pll 
is equivalent to the three commands 

print a.pll; print b.pll; print c.pll 

More than one iteration set can appear in a command. The 

corresponding element from each set is taken. For instance, the 
compound command 

rename >Smi th__di r> ( Jones Doe Brown) (Day White Green) 
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would expand into the commands 

rename >Smi th_di r> Jones Day 
rename >Sm? th_di r>Doe White 
rename >Smith dir>Brown Green 



Nested iteration sets are also allowed. Evaluation of 
parentheses occurs from the outside in. The principal use of 
nested iteration sets is to reduce typing when subsets of an 
element are repeated. For example/ 

createdir >Smi th_di rXnewXf i rst second) old>third) 

would create three directories 

>Smi th_di r>new>f i rst 

>Smi th__di r>new>second 

>Smith dir>old>third 



Active Strings 



The following hypothetical situation introduces the next 
feature of the command language. Suppose one wants to 
periodically delete the least recently used segment in a 
directory. After rejecting the notion of listing the directory 
and picking out the appropriate segment by hand/ one would 
probably write a small program (say/ ol dest_segment ) to perform 
the same task/ have it print the name of the segment/ and then 
delete the segment. Further thought leads one to the realization 
that it should be possible to give the results of ol dest_segment 
directly to the delete command. The desire generalizes into the 
notion of active strings where an act ? ve s tr i ng is defined to be 
an element of a command line which is immediately evaluated 
(executed) and the resultant value placed back into the command 
line. A program explicitly designed to be used in an active 
string is called an act i ve function . An active function must 
return a varying character string as its value. 

Since they are called from the user's terminal/ active 
functions do not follow the standard library subroutine practice 
of returning a status code. Instead/ upon detecting an error/ 
they call the subroutine act i ve_f nc_ er r_ wh i ch signals an error 
condition (see the MPM subroutine write-up for act i ve_ f nc_er r_) . 
Also, they are inherently more expensive than library subroutines 
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since they are designed to interact directly with a human user. 
For these reasons / they should not be called from a program. 

The delimiters of an active string are the left bracket ( [) 
and the right bracket (J). Thus, in terms of the hypothetical 
situation sketched above: 

delete [ol dest__segment] 

performs the desired task where ol dest_segment has been changed 
to return its value as a varying character string rather than 
printing its value on the terminal. The command processor scans 
the command line, discovers the active string, evaluates it, 
places the obtained value into the command line, discovers the 
terminator, evalutes what is left (which is "delete" as a command 
name and some character string as arguments), and then returns. 

To afford fuller generality, active functions can have 
arguments and active strings can be nested. Suppose one had a 
random name generating routine called namer which took an 
arbitrary two-character string as a "seed" and returned a 
32-character (or shorter) varying character string, then: 

rename [ol des t_segmentl [namer xz] 

would cause the least recently used segment to be renamed to 
whatever random name emerged from namer when the latter was 
invoked with xz as an argument. Now supposing one also had a 
random number generator called random for priming namer, 

rename Col dest_segment] [namer [random]! 

is also valid (provided random returns a varying character string 
value) . 

An implication of the use of active strings which deserves 
further emphasis is the fact that after being evaluated, the 
value is actually rescanned for active strings before being 
inserted into the command line. For example, if procedure alpha 
returned [beta] as its value, and x were some appropriate 
command, then 

x [alpha] 



would invoke x with whatever value procedure beta in turn 
returned. 
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In some cases, the user may not want the string returned by 
the active string to be rescanned for further active strings. To 
suppress this rescanning, one immediately precedes the active 
string with a vertical bar (|). Continuing the immediately 
preceding example, 

x lEalpha] 

would result in the invocation of x with [beta] as an argument. 
Note that all other scanning (e.g., for spaces) is performed on 
the returned string. 

Iteration can, of course, be combined with the above 
features. For example, suppose the program "bill" returned the 
character string "arthur robert fred". Then the command line 

print ([bill]) 

would expand into 

print (arthur robert fred) 

The command line finally obtained when all active strings 
have been processed is called the expanded command line. For 
example, in the case "print ([bill])" above, the expanded command 
line is "print (arthur robert fred)". 

The maximum length of the expanded command line is, by 
default, 128 characters. This size can be changed using the 
set__com_l i ne command (see the MPM command write-up). For the 
sake of efficiency, it is recommended that the size be left at 
128 characters except when a larger size is temporarily needed 
(to accommodate a large returned string from some active 
function, for example). 

For simplicity, all of the above examples have used active 
strings consisting of a single command line. In its most general 
form, an active string can consist of any number of legal command 
lines separated by semicolons. The value of the active string is 
the concatenation of the values of the command lines. For 
example, if the active string 

[act_fncl x] 

returns the value TURN and the active string 

[act_fnc2 y z] 



(c) Copyright, 1973, Massachusetts Institute of Technology 

and Honeywell Information Systems Inc. 



MULT ICS PROGRAMMERS 1 MANUAL 



l.k 



Command Language 
Command Language Environment 

Page 7 
7/11/73 



returns the value STYLE then the active string 

fact_fncl x; act_fnc2 y z] 
returns the value TURNSTYLE. 
Note 

The idea of active strings is taken from the TRAC® 1 anguage 
designed by Calvin N. Mooers. 

Concatenation 

Another desirable feature of a command language is the 
ability to form basic elements (i.e., character strings) by 
concatenation with nonbasic elements (e.g., the values of active 
strings). For example, suppose one has written an active 
function called work which returns the character string 
representation of the path name of one's working directory. It 
should then be possible to perform a command (presumably from 
some other directory) such as 

rename [work] >square_root sqrt 

and have the first argument to rename be the concatenation of the 
value of the work active function with the string ">square_root" . 
In the Multics command language, this facility is furnished in 
precisely the manner shown. That is, the value of a delimited 
element of a command is concatenated with the string or delimited 
element adjacent to it when there is no space between the two. 

Note that more than one delimited element can be 
concatenated. For example, 

delete Cwork] X [bi 1 U ) 

deletes the segments arthur, robert, and fred in the user's 
working directory where the active function "bill" is defined as 
above. 

Note also that concatenation is permissible in either 
direction with regard to the delimited string and the 
non-delimited string. For example, 

delete >project_di r>0oe>( [bi 1 1J ) 
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deletes the segments arthur, robert, and fred in the directory 
>project__di r>Doe. 

Concatenation was implicitly assumed in our description of 
i terat ion. 

Reserved Characters ajid Quoted Strings 

Note that in the context of the Multics command language, 
the following characters are reserved: space, quotation mark 
( fl ), semicolon (;), the new line character, left and right 
brackets ( £ and ]), left and right parentheses ("(" and ")"), and 
the vertical bar (|) when adjacent to the left bracket. 
Occasionally, however, it is necessary to use a reserved 
character without its special meaning. For example, we might 
want to pass a semicolon as an argument to a command. The 
character quotation mark (") is reserved for this purpose. 
Reserved characters within a quoted string (i.e., a string of 
characters surrounded by quotation marks) are treated as ordinary 
characters. Thus, 

rename ";" foo 

causes a semicolon to be passed as an argument to the rename 
command. Also, since a quotation mark is a reserved character, 
it may be desirable to suppress its special meaning. For this 
purpose, two adjacent quotation marks within a quoted string are 
interpreted as a single quotation mark. For example, 

delete »a ,,m B" 

causes the argument A f, B to be passed to the delete command. 

Notes 

The command processor can be called from a program by using 
the procedure cu_$cp. See the write-up of the subroutine cu_ in 
the MPM. See also the MPM Reference Guide section, The Multics 
Programming Environment, 
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CONSTRUCTING AMU INTERPRET 1NQ NAMES 

The various types of names used on Multics are constructed 
and interpreted according to certain conventions. The names in 
question are user names, segment names, command names, subroutine 
names, I/O stream names and condition names. 

User names are discussed in the MPM Reference Guide section, 
Access Control, since they are primarily used to specify access 
control information. 

A segment can be named in two ways. Its location in the 
storage system hierarchy is specified by its path name. The name 
by which it is known in a process is its reference name. The 
star convention and equal convention provide shorthand methods of 
specifying segment names. Offset names allow specification of 
externally known locations in a segment. 

Path Names 

As described in the MPM Introduction Chapter 3, Beginner f s 
Guide to The Use of Multics, each segment (or directory or link) 
in the Multics storage system has an entry in a superior 
directory. Any segment (or directory or link) can be found by 
following the appropriate entries from a designated directory 
through inferior directories until the desired segment (or 
directory or link) entry is reached. An absolute path name is 
just such a sequence of entry names starting from the root 
directory. A relative path name is a sequence relative to the 
current working directory. Path names, whether relative or 
absolute, are typically used as arguments to commands and 
subroutines. 

An entry name is a string of 32 or fewer ASCII characters. 
Only the greater-than (>) and less-than (<) characters are 
prohibited in entry names, since they are used to form path names 
as described below. Several other characters are not recommended 
for entry names — asterisk (*), question mark (?), percent sign 
(%) , equals ( = ) and dollar sign ($) — because standard commands 
attach special meanings to them. Each is explained below. 

In general, entry names consist of the upper- and 
lower-case alphabetic characters, the digits, the underscore (_) 
and the period (.), and must have at least one nonblank 
character. The underscore is used to simulate a space for 
readability; e.g., a segment might be named new_seg. (Including 
a space in an entry name is permitted, but is cumbersome since 
the command language uses spaces to delimit command names and 
arguments.) The period is used to separate components of an 
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entry name, where a component is a logical part of the name. 
Several system conventions depend on components. For example, 
compilers on Multics expect the language name to be the last 
component of the name of a source segment to be compiled; e.g., 
square_root.pl 1 for a PL/ I source segment. 

An absolute path name is formed from a sequence of entry 
names, each preceded by a greater-than character. The initial 
greater-than indicates that the entry name following it 
designates an entry in the root directory. Thus, an absolute 
path name has the form >f i rst__di r>second_di r>thi rd_di r>my__seg. 

The directory first_dir is immediately inferior to the root, 
second_dir is an entry in first_dir, etc. A maximum of 16 levels 
of directories is allowed from the root to the final entry name. 
The number of characters in the path name cannot exceed 168. 
Each intermediate entry in the chain can be either a directory or 
a link to a directory. The final entry can be a directory, a 
segment or a 1 ink. 

A relative path name looks like an absolute path name except 
that it does not contain a leading greater-than character, and 
can begin with less-than characters as explained below. It is 
interpreted by various commands to be a path name relative to the 
user's working directory. The simplest form of relative path 
name is the single name of an entry in the user's working 
directory. For example, the relative path name alpha refers to 
the entry alpha in the user's working directory. On a slightly 
more complex level, the relative path name sub_di r >beta refers to 
the entry beta in the directory sub_di r which is immediately 
inferior to the user's working directory. 

The less-than character can be used at the front (left end) 
of a relative path name to indicate that the directory 
immediately superior to the working directory is where the 
following entry name is to be found. This principle can be 
extended so that several less-than characters cause the superior 
directory several levels higher than the working directory to be 
searched for the first entry name in the relative path name. 

In the following examples, the user's working directory is 

>dirl>dir2>dir3>dirU 

A relative path name of 

new_seg 
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would designate the segment with the absolute path name 

>dirl>dir2>dir3>di rU>new_seg 
A relative path name of 

di r5>ol d__seg 
would designate the segment 

>dirl>dir2>dir3>diri*>dir5>old_seg 
A relative path name of 

<di rO>newer 
would designate the segment 

>dirl>dir2>dir3>dir0>newer 



A relative path name of 



<<<sampl e_di r>game_di r>chess 
would designate the segment 

>di rl>sample_di r>game_di r>chess 
Ihe star Convention 



Many commands that accept path names as input allow the 
final entry name in the path to be a star name. A star name is 
an entry name that identifies a group of entries in a single 
directory. Commands that accept star names perform their 
function for each directory entry identified by the star name. 

A star name identifies all entries in a directory having an 
entry name that matches the star name. A special type of 
matching is performed in which some character strings of the star 
name are compared with corresponding strings of the entry name, 
while other character strings of the entry name are ignored. If 
the star name strings match the entry name strings, then the 
entry name matches the star name. Therefore, the entries 
identified by a star name all have similar names. 
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Under the star convention/ the matching is performed 
according to the rules for constructing and interpreting star 
names listed below: 

1) A star name is an entry name. Therefore/ it is composed of 
a string of 32 or fewer ASCII printing graphics or spaces, 
none of which may be the less-than (<) or greater-than (>) 
character. Note that/ unlike an entry name/ a star name 
cannot contain control characters such as backspace/ tab, or 
new 1 i ne. 

2) A star name is composed of one or more nonnull components. 
This means that a star name cannot begin or end with a 
period (.)/ and cannot contain two or more consecutive 
periods . 

3) Each question mark (?) character appearing in a star name 
component is treated as a special character. The question 
mark matches any character that appears in the corresponding 
component and letter positions of the entry name. 

h) Each asterisk (*) character (loosely referred to as a star) 
appearing in a star name component is treated as a special 
character. The asterisk matches any number of characters 
(including none) appearing in the corresponding component 
and letter positions of the entry name. Only one asterisk 
can appear in each star name component/ except for a double 
star component as noted in the next rule. 

5) A star name component consisting only of a double star (**) 
is treated as a special component. The double star 
component matches any number of components (including none) 
in the corresponding component position of the entry name. 
Only one double star component can appear in a star name. 

Note that the rules above do not require that star names contain 
asterisks or question marks. Therefore/ an entry name that does 
not contain either of these special characters can be used as a 
star name/ as long as it does not contain any null components. 
Note too that the rules above impose no restrictions on the form 
of the entry names to be matched with the star name. Such names 
can contain null components that match only star name components 
of * or **. 

The following examples illustrate some common forms for star 
names. The entry name 
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*.pll 

identifies all two-component entries in the user's working 
directory that have pll as their second component; the path name 

sub_di r>my_prog.new. * 

identifies all three-component entries in the directory sub__dir 
(which is immediately inferior to the user's working directory) 
that have my_prog.new as their first and second components; and 

* 

and 

*.* 

identify, respectively, all one-component and two-component 
entries in the working directory. The entry name 

my_prog. ** 

identifies all entries with my_prog as the first (and possibly 
only) component; 

*.**.my_seg 

identifies all entries with two or more components of which the 
last is my_seg; 

**.pl 1 

identifies all entries with pll as the last (and possibly only) 
component; and 

** 

identifies all entries in the user's working directory. The 
entry name 

prog*. pi 1 

identifies all two-component entries whose first component begins 
with prog and has four or more characters, and whose second 
component is pll; 
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*__data 

identifies all one-component entries whose first component ends 
with _data and has five or more characters; and 

i nterest_*_data. * . * 

identifies all three-component entries whose first component 
begins with interests ends with _data, and has fourteen or more 
characters. Final ly, the entry name 

ad? 

identifies all three-character one-component entries in the 
user's working directory which begin with ad; 

j ?????????????? 

identifies all fifteen character one-component entries beginning 
with ! (called unique names because such names are generated by 
the un ique__chars_ subroutine and the unique active function); and 

sub_di r>prog?.**.pll 

identifies all entries in the directory sub_dir (which is 
immediately inferior to the user's working directory) with two or 
more components/ the first of which has five characters and 
begins with prog, and the last of which is pll. 

The Equal Convention 

Some commands that accept pairs of path names as their 
arguments (e.g., the rename command) allow the final entry name 
of the first path to be a star name, and the final name of the 
second path to be an equal name. An equal name is an entry name 
containing special characters that represent one or more 
characters from the entry names identified by the star name. 
Commands that accept equal names provide a powerful mechanism for 
mapping certain character strings from the first path name into 
the second path name of a pair. Such a mechanism helps to reduce 
the typing required for the second path name, and it can be 
essential for mapping character strings from the entry names 
identified by the star name into the equal name, because these 
characters strings are not known when the command is issued. 

Under the equal convention, the mapping of character 
strings from the star name into the equal name is performed 
according to the rules for constructing and interpreting equal 
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names given below: 

1) An equal name is an entry name. Therefore, it is composed 
of a string of 32 or fewer ASCII printing graphics or 
spaces/ none of which may be the less-than (<) or the 
greater-than (>) character. Note that/ unlike an entry 
name/ and equal name cannot contain control characters such 
as backspace/ tab, or new line. 

2) An equal name is composed of one or more nonnull components. 
This means that an equal name cannot begin or end with a 
period (.)/ and cannot contain two or more consecutive 
periods. 

3) Each percent (%) character appearing in an equal name 
component is treated as a special character. The percent 
represents the character in the corresponding component and 
letter position of the entry name identified by the star 
name. An error occurs if the corresponding character does 
not exist. 

k) Each equal sign (=) appearing in an equal name component is 
treated as a special character. The equal sign represents 
the corresponding component of the entry name identified by 
the star name. An error occurs if the corresponding 
component does not exist. An error also occurs if an equal 
sign appears in a component that also contains a percent 
character. Only one equal sign can appear in each equal 
name component/ except for a double equal sign component/ as 
noted in the next rule. 

5) An equal name component consisting only of a double equal 
sign (==) is treated as a special component. The double 
equal sign component represents all components of the entry 
names identified by the star name that have no other 
corresponding components in the equal name. From this 
definition/ it follows that if the double equal sign 
component represents (i.e./ corresponds to) any components 
of the entry name identified by the star name, then the 
equal name necessarily has the same number of components as 
the entry name. Only one double equal sign component can 
appear in an equal name. 

Note that the rules above do not require that equal names 
contain equal signs or percent characters. Therefore, an entry 
name that does not contain either of these special characters can 
be used as an equal name, as long as it does not contain any null 
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components. Note too that the rules above impose no restrictions 
on the form of the entry names identified by the star name. 
These names can contain null components. However/ the rename and 
addname commands cannot be called with an entry name that 
contains null components/ because these commands treat their 
arguments as either star names or equal names. The fs_chname 
command can be used to rename entries if names containing null 
components are accidentally created. 

The following examples illustrate how equal names might be 
used in rename and addname commands. The command 



rename random. data__base order. ■ 
is equivalent to 



rename random. data_ base ordered. data__base 
addname world. data =. stat ist ics =. census 



is equivalent to 



addname world. data world. stat istics world. census 



The command 



rename random. data. base 



is equivalent to 



rename random. data. base random. data 
The star convention is used in the command 



rename *.data_base =.data 



to rename all two-component entry names with data_base as their 
second component to have/ instead/ a second component of data. 
The command 



rename alpha beta. =. gamma 

is in error because the first name of the pair does not contain a 
component corresponding to the equal sign in the second name. 
The command 



rename program.pl 1 old_-.= 
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is equivalent to 

rename program, pi 1 ol d_program. pi 1 

and 

addname data first_=_set 

is equivalent to 

addname data f i rst_data^set 

The next rename command, which contains a double equal sign 
component/ 

rename one. two, three 1 . =- 

is equivalent to 

rename one. two. three 1. two. three 

and 

addname one. two. three. four 1.== .k 

is equivalent to 

addname one. two. three. four 1 . two . three. h 

Note that/ in the two examples above, the first name has 
components that are represented by the double equal sign in the 
second name of each pair. As a result/ the number of components 
represented by the equal name is the same as the number of 
components in the first name. On the other hand/ in the command 

addname able ==. baker .charl ie 

which is equivalent to 

addname able baker .charl ie 

the double equal sign does not represent any component of the 
first name. Component able of the first name is represented in 
the equal name by baker. As a result/ the equal name represents 
a greater number of components than there are in the first. The 
command 
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addname **.ec ==.absin 

uses the star convention to add a name to each entry with a name 
whose last component is ec. The last component of this new name 
is absin, and the first components (if any) are the same as those 
of the name ending in ec. Finally/ the command 



rename ???*.data 



renames all two-component entry names that have a last component 
of data and a first component containing three or more characters 
to have a first component that has been truncated to the first 
three characters and the same last component. Note that the 
command 



rename *.data 



may result in 
matching *.data 

Reference Names 



an error if 
has fewer than 



the first component 
three characters. 



of any name 



Procedures executing in a process need to refer by name to 
other segments known in that process. Such a name is a reference 
name. A reference name may be the same as an entry name of the 
segment/ or may be different. For example/ when a dynamic 
linkage fault occurs for a reference name, the linker searches 
(using search rules) for a segment which has an entry name 
identical to that reference name. A procedure call/ an 
invocation of a command through the command processor/ or a 
reference to an external data segment is of this type/ as is a 
segment made known by the hcs__$make_pt r subroutine. Search rules 
(telling which directories to search for the entry name) may be 
specified by the user or may be system defaults. The default 
search rules are described in the MPM Reference Guide section. 
The System Libraries and Search Rules. Alternatively/ the user 
may explicitly designate the reference name to be associated with 
a specified segment. The initiate command and the hcs_$i ni t iate 
and hcs_$ini tiate_count subroutines perform this function. In 
this case, the reference name need not have any similarity to any 
entry name of the segment. 

Since a reference name is associated only with segments made 
known in a process/ the same reference name may be used in two 
different processes to refer to two different segments. Also/ a 
reference name/segment binding exists only for the duration of 
the process in which it is specified. It is possible to break 
that binding by terminating the segment, thus causing all links 
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to that segment to be unsnapped and causing the segment to no 
longer be known in the process (by any reference name). Any 
reference name of a terminated segment can be used again in the 
process to refer to a different segment. (See the write-ups for 
the terminate and termi nate__ref name commands and the term_, 
hcs_$ termi nate_f i 1 e, and hcs_$ termi na te_seg subroutines.) 

Individual reference names can be unbound in a process 
without terminating the segment unless the reference name removed 
was the only one on the segment. (See the write-ups for the 
termi nate_single__ ref name command and for the term_, 
hcs_$termi nate_name, and hcs_$ termi nate_noname subroutines.) A 
user wishing to replace a system routine with one of this own by 
the same reference name might terminate that one reference name 
and initiate his routine by that same reference name: 



termi nate_s i ngle_ref name sys_prog 
initiate >my__di r>my__prog sys_prog 



Thereafter/ references to sys__prog would invoke his routine, 
my_prog/ with one exception. Other system routines bound to 
sys_prog would continue to invoke the system routine since those 
links had been presnapped when the routines were bound together. 

Note that the commands and the term__ subroutine unsnap 
dynamic links to any segment that has a linkage section/ whereas 
the hcs_ entry points do not unsnap links. 

Offset Names 

Procedures frequently have more than one entry point/ and 
data segments frequently have internal locations which are known 
externally by symbolic name. The names of the entry points and 
the internal locations are called offset names. Both designate 
symbolically an offset within the segment. The location 
specified may be refered to by the construction 
ref_name$of f set__name where the dollar sign separates the 
reference name and offset name. 



In many cases the entry point to a procedure has the same 
name as the segment itself (or the segment has several entry 
names corresponding to the names of its entry points). A 
shorthand notation allows the offset name to be assumed to be the 
same as the reference name. For example/ 



call square__root (n); 
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is interpreted to mean 

call square_root$square_root (n); 
and the command line 

rename a b 
is equivalent to 

rename$ rename a b 

It is worthwhile to remember that if the user has renamed 
one of his procedure segments (perhaps to preserve an old copy) 
or created a storage system link to a segment using a different 
name, he must thereafter use the full reference name/offset name 
construction when referring to that segment as a procedure 
external data segment. For example, a PL/ I subroutine compiled 
with subr_name as the label of its procedure statement/ and then 
renamed new_name must be referred to as new__name$ sub r_name . It 
is also important to not that if a reference name/segment binding 
has been established in a process, then merely renaming the 
segment does not break the association in that process. To do 
this, the segment must be terminated. 

Command , Subrout i ne . Cond i t ion and I /0 St ream Names 

These types of names all have some conventions in common. 

1) Each is permitted to be not more than 32 characters in 
1 ength . 

2) All ASCII characters are legal in any position except as 
noted in points 3 and k below. 

3) System subroutine names end in an underscore to prevent 
conflicts with subroutine names given by users. (I.e., the 
user may easily avoid conflicts by refraining from having an 
underscore as the last character of his subroutine names.) 

k) Condition and I/O stream names which are part of the system 
should end in an underscore to help prevent conflicts with 
names given by users. A glance at the MPM Reference Guide 
sections, List of System Conditions and Default Handlers, 
and List of Names with Special Meanings, reveals many system 
condition and I/O stream names which do not observe this 
convention. These names were incorporated into the system 
before this convention was established. 
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COMMAND AND ACTIVE FUNCTION NAME ABBREVIATIONS 

The following is a list of abbreviations for commands and 
active functions. The abbreviations are also listed immediately 
after the command or active function name in the individual 
write-ups. For example. 



Name ; abbrev, ab 



APP^ey i a t i on 


command Name 


aa 


alm_abs 


ab 


abbrev 


abc 


adjust__b i t_count 


ac 


arch i ve 


an 


addname 


as 


archi ve_sort 


bd 


b i nd 


br 


bas i c_run 


bs 


bas i c_system 


car 


cancel _abs_request 


cd 


created i r 


cdr 


cancel_daemon_request 


cdwd 


change_def aul t_wdi r 


cem 


change_er ro r_mo d e 


• 

CIS 


check_i nf o_segs 


CO 


consol e__output 


cp 


copy 


cpa 


• • 

compare__asc i i 


cr 


create 


cwd 


change__wdi r 


da 


deleteacl 


db 


debug 


dc 


deletecacl 


dcm 


decam 


den 


di splay_component__name 


dd 


delete_di r 


df 


del eteforce 


did 


delete_iacl_ di r 


dirs 


di rector ies 


di s 


del ete_i acl_ seg 


dl 


delete 


dn 


deletename 


dp 


dpr i nt 


dpn 


dpunch 


ds 


dump_segment 


e 


enter 


ear 


enter_abs__request 


ec 


exec_.com 
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ep 


enterp 


?a 


"P /""V 4- •» f% —5 w 

rort ran_aDs 


T 1 


TorrnaL - _i i ne 


TO 


f i 1 e_outpu t 


T t 


to r t ran 


gel 


get__com__i i ne 


gpn 


get patnname 


gq 


getquota 


net 


no I a 


hmu 


how_many_jjsers 


in 


ini tiate 


ind 


i ndent 


1 


logi n 


la 


1 i stacl 


lar 


1 i st_abs__requests 


lc 


1 i stcacl 


lep 


1 isp_compi ler 


ldr 


1 i st_daemon_requests 


I i J 

I I d 


1 i st_i acl__di r 


1 is 


1 i st__i acl_seg 


1 k 


1 i nk 


1 1 


1 i ne__l ength 


In 


1 i s tnames 


1 rn 


1 i s t_ref__names 


Is 


1 1 St 


1 1 


1 i stota 1 s 


ml 

m i 


ma i 1 

nict I I 


mp t 


rnaKe_per use__iex t 


mq 


movequo La 


IT1V 


1 1 ivs V c 


none 1 rs 


nona i rector i es 




nonsegmen is 




oil abs 


pa t 


p r I n L a t LaCn_Ca D 1 e 


pbm 


p r i n t d i n d__ma p 


pa i 


print aar tmouin_i lurary 


pdwa 


pr i n t_def au 1 t_wd i r 


Pg 


progress 


pgt 


page_trace 


Pi 


program__i nter rupt 


Pli 


pr int_l i nk_i nfo 


pi u 


print_l i nkage__usage 


pmotd 


pr i nt__motd 


pr 


pr i nt 


psr 


pr int_search_rules 


Pt 


peruse_text 


pwd 


pr i nt__wdi r 


qx 


qedx 
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ra 


reor de r a rch i ve 


rq 


reor aer aren i ve 


r a 


ready_of f 


rra 


1^ i i y\ f~\ r r 3 r\ O 

rUnOT l_aDS 


rr 


runoff 


rdn 


ready_on 


rdy 


ready 


re 


repr i nt_er ror 


rl 


release 


rn 


rename 


ru 


resou rce usage 


sa 


setacl 


_ i_ _ 

SDC 


set_b i t_ count 


sc 


se tcac i 


SC 1 


set com_i i ne 


sdl 


set_da r tmouth__l ibrary 


segs 


segments 


ST 


so r t_t i 1 e 


sid 


set_i acl_di r 


sis 


set_i ad_seg 


sr 


start 


ssd 


set_search_di rector i es 


ssf 


set_saf ety_sw__of f 


ssn 


s e t__s a f e t y_sw_o n 


ssr 


set_search__rul es 


St 


status 


tc 


truncate 


tm 


termi nate 


tmr 


termi nate_ref name 


tms 


termi nate_segno 


ts 


trace_stack 


ul 


unl ink 


v2pa 


v2pl l__abs 


wh 


where 


ws 


wal k_subt ree 
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ALPHABETICAL L I $T OF ACT jV^ FUNCT i ON$ 

The active functions of interest to most Multics users are 
documented in this and seven other MPM Reference Guide Sections: 
Logical Active Functions, Arithmetic Active Functions, Character 
String Active Functions, Segment Name Active Functions, Date and 
Time Active Functions, Question Asking Active Functions, and User 
Parameter Active Functions. The MPM Reference Guide section, The 
Command Language, describes the purpose of active functions and 
illustrates their use. 

The following alphabetical list of the active functions 
available to Multics users includes the grouping to which each 
active function belongs; i.e., indicates which write-up contains 
its description. 



Apt* i v/ o f- 1 1 n ^ t* i nn 




aiiu 


1 r\ <T ■ f a 1 
1 Ug I \*a 1 


ua L c 


UdLc dliU L 1 me 


ua Lc L i Hie 


ud Lc ana Lime 


day 


d;if*f» and time 


dav name 


date and time 


di rectories 


segment name 


di rectory 


segment name 


di vi de 


ar i thmet ic 


entry 


segment name 


equal 


logi cal 


exi sts 


logical 


files 


segment name 


format_l i ne 


character string 


get_pathname 


segment name 


greater 


logi cal 


home_d i r 


segment name 


hour 


date and time 


i ndex 


character string 


index__set 


character string 


length 


character string 


less 


logi cal 


1 inks 


segment name 


long_date 


date and time 


mi nus 


ari thmet ic 


mi nute 


date and time 


mod 


ari thmet i c 


month 


date and time 


month_name 


date and time 


nondi rector ies 


segment name 


nonl i nks 


segment name 


nonsegments 


segment name 



© Copyright, 1973, Massachusetts Institute of Technology 

and Honeywell Information Systems Inc. 



1.8 MULT ICS PROGRAMMERS 1 MANUAL 



Active Functions 

Command Language Environment 

Page 2 



not 


1 og i ca 1 


o r 


1 og i ca 1 


path 


segment name 


pd 


segment name 


plus 


ar i thmet i c 


query 


question asking 


response 


question asking 


segments 


segment name 


st r i ng 


character string 


strip 


segment name 


str i p__entry 


segment name 


substr 


character string 


suf f i x 


segment name 


time 


date and time 


times 


ar i thmet i c 


unique 


segment name 


user 


user parameter 


wd 


segment name 


year 


date and time 
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■LOGICAL ACTIVE FUNCTIONS 



The active functions of interest to most Multics users are 
documented in this and seven other MPM Reference Guide sections: 
Alphabetical List of Active Functions, Arithmetic Active 
Functions/ Character String Active Functions/ Segment Name Active 
Functions/ Date and Time Active Functions/ Question Asking Active 
Functions/ and User Parameter Active Functions. The MPM 
Reference Guide section/ The Command Language, describes the 
purpose of active functions and illustrates their use. Note that 
in a command line an active function must be enclosed in square 
brackets. However/ those brackets have been omitted from usage 
descriptions in this wirte-up. They are included in examples. 

The following active functions return a character string 
value of either "true" or "false". They are intended to be used 
with the &if control statement of the exec__com command. (See the 
MPM write-up for exec__com.) 

Name : and 

This active function returns the value "true" if both of its 
arguments are true. Otherwise, it returns the value "false". 



Name : or 

This active function returns the value "true" if either or 
both of its arguments are true. Otherwise/ it returns the value 

"false". 



Usage 



and argl arg2 



1) argl 



are character strings that must have one of 

the values "true" or "false"; if not/ an 

error diagnostic is issued and the value is 
undef i ned. 



Usage 



or argl arg2 



1) argi 



are character strings that must have one of 

the values "true" or "false"; if not, an 

error diagnostic is issued and the value is 
undef i ned. 
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Name : not 

This active function returns either "true" or "false", 
whichever is the opposite of the value of its argument. 

Usage 

not arg 

1) arg is a character string. If arg = "true", then 

"false" is returned. If arg = "false", then 
"true" is returned. Otherwise an error 
diagnostic is issued. 



Name : equal 

This active function returns the value "true" if its 
arguments are equal (i.e., identical). Otherwise, it returns 
value "false". 

Usage 

equal argl arg2 
1) argi are any character strings. 



two 
the 



Name : greater 



This active function returns the value "true" 
of the first argument is greater than the value of 
argument. Otherwise, it returns the value "false". 



f the value 
the second 



Usage 



greater argl arg2 



1) argl 



are character strings. If both argl and arg2 
are character string representations of 
single-precision fixed binary integers, then 
a numeric comparison is made. Otherwise, the 
comparison is made a character at a time, 
starting from the left, using the ASCII 
collating sequence. 
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Name: less 



This active function returns the value "true 11 if the value 
of the first argument is less than the value of the second 
argument. Otherwise, it returns the value "false". 

Usage 

less argl arg2 

1) argj_ are character strings. The comparison is 

made as described above in the greater active 
function. 

Name : exists 

This active function checks for the existence of various 
types of items, depending on the value of a key. 



Usage 



exists key arg 



1) key 
entry 



branch 
segment 

di rectory 

link 

non_nul 1_1 i nk 
argument 



can have any of the following values: 

returns "true" if an entry with path name arg 
exists; otherwise it returns "false". 

returns "true" if a branch with path name arg 
exists; otherwise it returns "false". 

returns "true" if a segment with path name 
arg exists; otherwise it returns "false". 

returns "true" if a directory with path name 
arg exists; otherwise it returns "false". 

returns "true" if a link with path name arg 
exists; otherwise it returns "false". 

returns "true" if a link with path name arg 
exists and points to an existing segment or 
directory; otherwise it returns "false". 

returns "true" if it has been passed an 
argument; otherwise it returns "false". 
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2) arg is the argument described for each possible 

value of key. 

Exampl e 

The following example illustrates the use of one of the 
active functions described in this write-up. It involves the use 
of the &lf control statement of the exec_com command. (See the 
MPM write-up for exec_com. ) 

&if Cequal [wdj [home__di r]l 

&then &goto elsewhere 

&else change__wdir [home_dir3 

This example compares the path name of the working directory 
with the path name of the home directory, and if they are not the 
same changes the working directory to be the home directory. 



(c) Copyright, 1973, Massachusetts Institute of Technology 

and Honeywell information Systems Inc. (END)* 



MULT ICS PROGRAMMERS 1 MANUAL 



1.10 



Command Language Environment 

10/1/73 



ARITHMETIC ACTi VE FUNCTIONS 

The active functions of interest to most Multics users are 
documented in this and seven other MPM Reference Guide sections: 
Alphabetical List of Active Functions/ Logical Active Functions/ 
Character String Active Functions/ Segment Name Active Functions/ 
Date and Time Active Functions/ Question Asking Active Functions/ 
and User Parameter Active Functions. The MPM Reference Guide 
section/ The Command Language, describes the purpose of active 
functions and illustrates their use. Note that in a command line 
an active function must be enclosed in square brackets. However/ 
those brackets have been omitted from usage descriptions in this 
write-up. They are included in examples. 

The following active functions all perform some arithmetic 
operation on their arguments and return the character string 
representation of the result. 

Name : plus 

This active function returns a value that is the character 
string representation of the sum of its arguments. 

Usage 

plus argl . . . argn 

1) ar&L are character string representations of 

single-precision fixed binary integers. 

Name : minus 

This active function returns a value that is the characater 
string representation of the difference of its two arguments; 
i.e./ its first argument minus its second argument. 

Usage 

minus argl arg2 

1) argl are character string representations of 

single-precision fixed binary integers. 

Name : times 

This active function returns a value that is the character 
string representation of the product of its arguments. 
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Usage 

times argl . . . argn 

1) argl are character string representations of 

single-precision fixed binary integers. 

Name ; divide 

This active function returns a value that is the character 
string representation of the result of dividing its first 
argument by its second. 

Usage 

divide argl arg2 

1) argi are character string representations of 

single-precision fixed binary integers. 

Name ; mod 

This active function returns a value that is the character 
string representation of its first argument taken modulus its 
second argument. 

Usage 

mod argl arg2 

1) argl are character string ..representations of 

single-precision fixed binary integers. 

Njme.; min 

This active function returns a value that is the character 
string representation of the numerical minimum of its arguments. 

Usage 

mi n argl . . . argn 

1) argl are character string representations of 

single-prevision fixed binary numbers. 
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Name : max 

This active function returns a value that is the character 
string representation of the numerical maximum of its arguments. 

Usage 

max argl . . . argn 

1) argn. are character string representations of 

single prevision fixed binary numbers. 

Example 

The following example illustrates the use of one of the 
active functions described in this write-up. 

set_bi t_count my_seg Ctimes 672 36] 

This example sets the bit count of my_seg (assumed to 
contain 672 words of information) to 2U,192 which is the product 
of 672 and 36. 
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The active functions of interest to most Multics users are 
documented in this and seven other MPM Reference Guide sections: 
Alphabetical List of Active Functions, Logical Active Functions/ 
Arithmetic Active Functions, Segment Name Active Functions, Date 
and Time Active Functions, Question Asking Active Functions, and 
User Parameter Active Functions. The MPM. Reference Guide 
section, The Command Language, describes the purpose of active 
functions and illustrates their use. Note that in a command line 
an active function must be enclosed in square brackets. However, 
those brackets have been omitted from usage descriptions in this 
write-up. They are included in examples. 

The following active functions return the results of various 
operations on one or more character strings. 

Name: length 

This active function returns a value that is the character 
string representation of the number of characters in a specified 
str i ng 

Usage 

length arg 

1) arg is a character string. 

Name : index 

This active function returns a value that is the character 
string representation of the character position in the first 
argument where a substring matching the second argument begins. 

Usage 

index argl arg2 
1) argl are character strings. 

Name : substr 

This active function returns a value that is the character 
string representation of a substring of the first argument 
beginning at the character position specified by the second 
argument and having a length as specified by the third argument. 
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Usage 

substr argl arg2 arg3 
1) argl is a character string. 



2) arg2, arg3 are character string representations of 

single-precision fixed binary integers. If 

arg3 is omitted/ it is assumed to be the 
length of argl minus arg2, so that the value 

returned is the rest of argl beginning with 
the arg2-th character. 

Name : index_set 

This active function returns a value that is the character 
string representation of the numbers from 1 to the number 
specified, with a space between successive numbers. This active 
function is useful within an iteration in a command line. 



Usage 

index_set arg 

1) arg is a character string representation of a 

single-precision fixed binary integer. 

Name ; string 

This active function returns its input arguments, separated 

from one another by a single space, as a quoted character string. 
By using string, the user can treat the results of one or more 

active functions as a single character string. 
Usage 



str i ng argl . . . argji 



1) argj_ are the optional input arguments that are to 

be returned as a single character string. If 
no input arguments are present, then string 
returns a null character string. If one or 
more arguments are present, then any quotes 
in these are doubled when the argument is 
placed in the quoted return string, as 
required by the Multics command language 
convention for quoted strings. 
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Name. : format_J i ne/ fl 

This active function returns a formatted character string 
that is constructed from a control string and other optional 
input arguments. Quotes are placed around the return value so 
that the command processor treats i t as a single argument. Any 
quotes contained in the return value itself are doubled when the 
value is placed in quotes, as required by the Multics command 
language convention for quoted strings. 

Usage 

format_line control_str i ng argi ... argri 

1) control_str i ng is an ioa_ control string that is used to 

format the return value of the active 
function. It can contain control characters 
within it. If no control characters occur, 
the string itself is returned as the value of 
the active function. If control characters 
exist, they govern the conversion of 
successive additional arguments which are 
expanded into the appropriate characters and 
inserted into the return value. The MPM 
write-up of the ioa_ subroutine describes the 
control characters that can be used with 
ioa_. Of these, ""d, "o, T , "e, "p, "w, and 
^A cannot be used with the format_line active 
function, because they control the conversion 

of argument types that cannot be processed by 
the command processor, and hence, cannot be 
input to an active function. 

2) argj. are optional input arguments that are 

substituted in the formatted return value, 
according to the ioa_ control string. 

Name : search 

This active function returns a value that is the character 
string representation of the character position in the first 
argument that contains a character matching any character in the 
second argument. 
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Usage 

search argi ... arg2. 

1) argl is the character string to be searched. 

2) arg2 is the set of characters searched for. 
Name : verify 

This active function returns a value that is the character 
string representation of the character position in the first 
argument that contains a character not matching any character in 
the second argument. 

Usage 

ver i f y argl . . . arg2 

1) argl is the character string to be verified. 

2) arg2 is the set of characters searched for. 
Examol es 

The following examples illustrate the use of two of the 
active functions described in this write-up. One of the examples 
involves the use of the &if control statement of the exec_com 
command. (See the MPM write-up for exec_com. ) 

delete seg ([index_set 15]) 

This example is equivalent to the command line 

delete seg(l 2 3 k 5 6 7 8 9 10 11 12 13 1U 15) 

to delete the 15 segments segl, seg2 / segl5. 

&if [query If ormat_J i ne "Is "a a good date? 11 [longdate]]] 
&then Sprint Beginning execution. 
Seise Squit 

This example might result in the following dialogue. Note 
that the user's response has been underlined for the sake of 
clari ty. 

Is November 22, 1972 a good date? ves 
Beginning execution. 
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SEGMENT NAME ACT i VE FUNCTION'S 

The active functions of interest to most Multics users are 
documented in this and seven other MPM Reference Guide sections: 
Alphabetical List of Active Functions/ Logical Active Functions, 
Arithmetic Active Functions, Character String Active Functions, 
Date and Time Active Functions, Question Asking Active Functions, 
and User Parameter Active Functions. The MPM Reference Guide 
section, The Command Language, describes the purpose of active 
functions and illustrates their use. Note that in a command line 
an active function must be enclosed in square brackets. However, 
those brackets have been omitted from usage descriptions in this 
write-up. They are included in examples. 

The following active functions return a segment path name or 
entry name or some part thereof. Some of them perform 
manipulations on an input string to produce the output string. 
One returns a unique character string that is commonly used as 
the entry name of a segment. 

Name ; home__dir 

This active function returns the path name of the user's 
home directory (usually of the form >user_di r__di r >Proj ect>Person) 
as obtained by a call to user_info__$ homed i r . 

Usage 

home__d i r 
Name ; pd 

This active function returns the path name of the process 
directory of the process in which it is invoked. 

Usage 

Pd 

Name : wd 

This active function returns the path name of the working 
directory of the process in which it is invoked. 

Usage 

wd 
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Name : get_pathname, gpn 

This active function returns the absolute path name of the 
segment that is designated by the reference name or segment 
number specified. Reference names are discussed in the MPM 
Reference Guide section, Constructing and Interpreting Names. 

Usage 

get_pathname -control_arg- arg 

1) control__arg if present, can be -name, in that case the 

following argument (which looks like an octal 
segment number) is to be interpreted as a 
segment name. 

2) arg is a reference name or segment number (octal) 

known to this process. 

Name : path 

This active function returns the absolute path name of the 
specified segment. 

Usage 

path arg 

1) arg is a segment name. 

Name : directory 

This active function returns the directory portion of the 
absolute path name of the specified segment. 

Usage 

directory arg 
1) arg is a segment name. 

Name : entry 

This active function returns the entry name portion of the 
absolute path name of the specified segment. 
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Usage 

entry arg 

1) arg is a segment name. 

Name strip 

This active function returns the absolute path name of the 
specfied segment after having removed the last component of the 
entry name, if one exists or if it matches a specified character 
str i ng. 

Usage 

strip argl -arg2- 

1) argl is a segment name. 

2) arg2 is an optional character string that/ if 

present and if it matches the last component 
of the entry name portion of argl/ is removed 
from that entry name. If arg2 is not given, 
any last component is removed from the entry 
name portion of argl/ assuming argl has more 
than one component in its entry name. 

Name s str i p_ entry, spe 

This active function returns the entry name portion of the 
absolute path name returned by the strip active function. 

Usage 

strip_entry argl arg2 

1) argl is a segment name. 

2) arg2 is as described above under the strip active 

function. 

Name : suffix 

This active function returns the last component of the entry 
name portion of the specified segment. If that entry name has 
only one component, it returns the null string. 
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Usage 

suffix arg 
1) arg is a segment name. 

Name : unique 

This active function returns a unique character string as 
generated by unl ique_ chars_ (see the MPM write-up). 

Usage 

unique 
Name : files 

This active function returns the names (separated by 
blanks) of all directories/ segments/ and links matching 
starname. 

Usage 

files starname 

1) starname is a path name for which the entryname 

portion (optionally) contains stars to be 
interpreted according to the star convention. 
(See the MPM Reference Guide section. 
Constructing and Interpreting Names.) 

Name : segments, segs 

This active function returns the names (separated by blanks) 
of all segments matching starname. 

Usage 

segments starname 

1) starname is as described above under the files active 

f unct ion. 

Name : directories, dirs 

This active function returns the names (separated by blanks) 
of all directories matching starname. 
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Usage 



directories starname 



1) starname 



is as described above under the files active 
function. 



Name ; links 

This active function returns the names (separated by blanks) 
of all links matching starname. 



Usage 



links starname 



1) starname 



is as described above under the files active 
function. 



Name ; nonlinks/ branches 

This active function returns the names (separated by blanks) 
of all segments and directories matching starname. 



Usage 



nonlinks starname 



1) starname 



is as described above under the files active 
function. 



Name ; nondi rector i es / nondirs 

This active function returns the names (separated by blanks) 
of all segments and links matching starname. 



Usage 



nondi rector i es starname 



1) starname 



is as described above under the files active 
function. 
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Name ; nonsegments, nonsegs 

This active function returns the names (separated by blanks) 
of all directories and links matching starname. 

nonsegments starname 

1) starname is as described above under the files active 

function, 

Fxamples 

The following examples illustrate the use of three of the 
active functions described in this write-up. 

status Cget_pathname refnamel 

This example invokes the status command with the path name 
of the segment that is known to the process by the reference 
name, refname. 

list *.pll -p [d! rectory [wdJJ 

This example lists PL/I source segments in the directory 
immediately superior to the working directory. 

dprint [segs *.plll 

This example invokes the dprint command to have copies 
printed of all 2-component PL/ I source segments in the working 
di rectory . 
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The active functions of interest to most Multics users are 
documented in this and seven other MPM Reference Guide sections: 
Alphabetical List of Active Functions, Logical Active Functions, 
Arithmetic Active Functions, Character String Active Functions, 
Segment Name Active Functions, Question Asking Active Functions, 
and User Parameter Active Functions. The MPM Reference Guide 
section, The Command Language, describes the purpose of active 
functions and illustrates their use. Note that in a command line 
an active function must be enclosed in square brackets. However, 
those brackets have been omitted from usage descriptions in this 
write-up. They are included in examples. 

The following active functions return information about 
dates and times. 

Name : date 

This active function returns a date abbreviation in the form 
"mm/dd/yy"; e.g., "02/20/73". 

Usage 

date argJL . . . arga 

1) argi are optional input arguments that determine 

the date and time for that information is 
returned. These arguments must be in a form 
acceptable to the convert_date_to_binary 
subroutine (see the MPM write-up). If no 
arguments are specified, information about 
the current date and time is returned. 

Name : date_time 

This active function returns a date abbreviation, a time 
from 0000.0 to 2359.9, a time zone abbreviation, and a day of the 
week abbreviation in the form: "mm/dd/yy hhmm.m zzz www"; e.g., 
"08/07/72 0945.7 est Mon. 

Usage 

date_time argi ... arga 

1) argi are as described above under the date active 

function. 
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Name: day 

This active function returns the 1- or 2-digit number of a 
day of the month, from 1 to 31; e.g., ,, 7". 

Usage 

day argi ... . arga 

1) argi are as described above under the date active 

function. 

Name : day_name 

This active function returns the name of day of the week; 
e.g., "Monday". 

day__name argl ... arga 

1) argi are as described above under the date active 

f unct ion. 

Name? hour 

This active function returns the 1- or 2-digit number of an 
hour of the day, from 0 to 23; e.g., "9". 

Usass 

hour argl . . . arga 

1) argi are as described above under the date active 

function. 

Name : Tong_date 

This active function returns a month name, a day number, and 
a year in the form: "month day, year", e.g., "August 7, 1972". 

Usa^e 

Tong_date argl ... arga 

1) argi are as described above under the date active 

f unct ion. 
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Name : minute 



This active function returns the 1- or 2-digit number of a 
minute of the hour, from 0 to 59; e.g., "US". 



Usage 



minute argi ... argn 



1) argi 



are as described above under the date active 
f unct ion. 



Name : month 

This active function returns the 1- or 2-digit number of a 
month of the year, from 1 to 12; e.g., "8". 



usage 



month argi ... argn 



1) argi 



are as described above under the date active 
function. 



Name : month_name 

This active function returns the name of a month of the 
year; e.g., "August". 



Usage 



montlwiame argi ... arga 



1) argi 



Name : time 



are as described above under the date active 
f unct ion. 



This active function returns a 4-digit time of day in the 
form "hh:mm" where 00 < hh 1 23 and 00 < mm 1 59; e.g., "09:1*5". 



Usage 



time argi . . . argn 



1) argi 



are as described above under the date active 
f unct ion. 
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Name : year 

This active function returns the 2 -digit number of a year of 
the century; e.g., "73". 

Usage 

year argl . . . arna 

1) argi are as described above under the date active 

function. 

Example 

The following example illustrates the use of one of the 
active functions described in this write-up. 

enter_abs_request abs_seg -time Ldate [month 1 month!/ 11 

This example enters an absentee request for deferred 
execution to start at the beginning of the next month. The 
arguments to the month active function indicate that "1 month" 
should be added to the current date to get the date from which 
the month is to be calculated. The "/I" when concatenated with 
the calculated month forms a string such as "2/1" • 
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QUESTION AS KiN Q AQTiV£ FUNCTIONS 

The active functions of interest to most Multics users are 
documented in this and seven other MPM Reference Guide sections: 
Alphabetical List of Active Functions, Logical Active Functions/ 
Arithmetic Active Functions, Character String Active Functions, 
Segment Name Active Functions, Date and Time Active Functions, 
and User Parameter Active Functions. The MPM Reference Guide 
section, The Command Language, describes the purpose of active 
functions and illustrates their use. Note that in a command line 
an active function must be enclosed in square brackets. However, 
those brackets have been omitted from usage descriptions in this 
write-up. They are included in examples. 

The fol lowing act ive functions return the answer given by a 
user in response to a specified question. 

Name; query 

This active function asks the user a specified question and 
returns the value "true" if the user's answer was "yes" or the 
value "false" if the user's answer was "no". 



Name : response 

This active function asks the user a specified question and 
returns the answer typed by the user in response. 



Usage 



query arg 



1) arg 



is a question to be asked. It should be 
worded so as to require a "yes" or "no" 
answer . 



Usage 



response arg 



1) arg 



is a question to be asked the user. 
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Example 

The following example illustrates the use of one of the 
active functions described in this write-up. It involves the use 
of the &if control statement of the exec_com command. (See the 
MPM write-up for exec_.com.,) 

&if CQuery "Do you wtsh to continue? "1 
&then 

&eTse &qu 1 1 

This example causes the exec_.com to continue or quit 
depending on the user's answer. 
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USER PA3AM5TE R ACTIVE FUNCTIONS 



The active functions of interest to most Multics users are 
documented in this and seven other MPM Reference Guide sections: 
Alphabetical List of Active Functions/ Logical Active Functions/ 
Arithmetic Active Functions, Character String Active Functions/ 
Segment Name Active Functions, Date and Time Active Functions/ 
and Question Asking Active Functions. The MPM Reference Guide 
section/ The Command Language/ describes the purpose of active 
functions and illustrates their use. Note that in a command line 
an active function must be enclosed in square brackets. However/ 
those brackets have been omitted from usage descriptions in this 
write-up. They are included in examples. 



The following active function returns 
obtained from system data bases. 



user parameters 



Name : user 

This active function returns various user parameters. 

Usage 

user arg 
1) arg 
name 
project 
login_date 



1 og i n__t i me 
. anonymous 
secondary 

absentee 
term_i d 



can have one of the following values: 
returns the user name at log in time, 
returns the user project ID. 

returns the date at log in time. The date is 
of the form "mm/dd/yy". 

returns the time of log in. The time is of 
the form "hhmm.t" . 

returns "true" if the user is an anonymous 
user; otherwise it returns "false". 

returns "true" if the user is currently 
subject to preemption; otherwise it returns 
"false". 

returns "true" if the user is an absentee 
user; otherwise it returns "false". 

returns the user's terminal ID code. It is 
"none" if the user's terminal does not have 
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the answer back feature. 



term_type 



returns the user's terminal type, 
have one of the following values: 

"Absentee" 

"Network" 

"1050" 

»27i*l" 

"IBM2741" 

"TTY33" 

"TTY37" 

"TN300" 

"ARDS" 



1 1 can 



The terminal types "2741" and "IBM2741" 
differ in that "IBM2741" designates a 
standard IBM 2741 terminal and "2741" 
designates a 2741 terminal that has been 
modified according to MIT specifications. 
The modification prevents keyboard locking 
after a carriage return. A "2741" terminal 
can be made to look exactly like an "IBM2741" 
terminal by placing its INHIBIT AUTO EOT 
switch in the off position. 



cpu_secs 



!og_t ime 



returns the user's CPU usage, in seconds, 
since log in. The usage is of the form 
"sss.t" with leading zeros suppressed. 



returns the user 
since log in. 
"mmm.t". 



connect time, in minutes, 
The time is of the form 



preempt i on_t i me 



if the user is a primary user, returns the 
time at which he becomes eligible for group 
preemption. The time is of the form 
"hhmm.t". 



brief_bit 



returns "true" if the user 
-brief control argument in 
otherwise, returns "false". 



specified the 
his login line; 



protected 



if the user is currently a primary user and 
protected from preemption, returns 
otherwise, returns "false". 



"true"; 
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absin if the user is an absentee user, this returns 

the absolute path name of his absentee input 
segment including the .absin suffix; 
otherwise returns a null string. 

absout if the user is an absentee user, returns the 

absolute path name of his absentee output 
segment; otherwise, returns a null string. 

Example 

The following example illustrates the use of one of the 
active functions described in this write-up. 

ioa_ [user login_time] 

This example causes the time the user logged in to be 
printed at the user's terminal. 
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THE MULT ICS SUBROUTINE REPERTOIRE 



The following facilities are the ones considered to be part 

w i imu i 111,0 a 1 1 vj a i c ucsCi i ucu 111 in i s iiiciiua i i w c v. a i i cu 

specifications on each of the subroutines mentioned below can be 
found / filed in alphabetical order by name, in the MPM Reference 
Guide section, Subroutines. 

In addition, the user should consult the list of items in 
the Author Maintained and/or Installation Maintained Library at 
his installation, since local library procedures can 
substantially extend the standard subroutine repertoire. 
Documentation on the Author Maintained and/or Installation 
Maintained Library is supplied by the local installation. 

The subroutine repertoire is organized by function Into the 
fol lowing groups: 

Storage System, Utility Routines 

Storage System, Access Control and Rings of Protection 
Storage System, Supervisor Entries for Manipulating Directories 
and Segments 

Storage System, Supervisor Entries for Manipulating an Address 
Space 

Clock and Timer Services 

Subroutine Call and Argument Utilities 

Command Environment Utility Procedures 

I/O System Facilities 

Error Handling Facilities 

Routines to Convert Some Data Type To and From a Character String 

Representation 
Object Segment Manipulation Routines 
Miscellaneous Procedures 
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1) Storage System, Utility Routines 



change_wd i r_ 


changes the current working 




a i r eciory 


cnecK^s tar name.. . 


cnecKs an entry name r or correci 




construction as a star name 


copy_acl_ 


copies access control list (ACL) 




from one segment to another 


copy_names_ 


copies all names from one segment 




to anotner 


copy__seg_ 


copies a segment 


de 1 e te_ 


deletes a segment or unlinks a link 


aecoce_en t ry nainc_ 


9 p i i ib a proccuu re rerer entc i n lo 




** of eronrc nsmo anrl nf f cot n^nio 
i ci ci ciicc name aiiu ut i 5cl iiaiiic 


a +■ Amis 1 r\ omo 

get equg 1 1 name 


! mnl oinontc f ho e f rtf aire c u c t on anna 1 
1 flip 1 elllc 1 1 L b tile o LUi age b y b t clll cM Ud 1 




convent i on 


e x pa no_po t n 


conver is relative pa lm naine 




LU aDbOIULc pain name 


gel OcToU 1 t WO 1 r 


rcLur ns trie cciauit wur King 




di rectory 


get — pd i r 


returns path name of process 




di rectory 


ge t_wd i r_ 


returns path name of current working 




di rectory 


ma tch__s tar name_ 


determines if an entry name matches 




a star name 


move_names_ 


moves names from one segment to 




another 


surf i xed_name__ 


manipulates suffixes on storage 




system entry names 


term_ 


removes a segment from the address 




c r\ — » /-^ <-\ — * tr\ r\ "5 1 r r\ i in f nine i r\ \l 

space ana a i so unsnaps any 




ciiKrrviit t no 1 i nkace r\ i f 
suuiuuiiiic i i i^a&c iw i *- 


:orage System, Access 


control ana Kings or protection 


copy_ad_ 


copies ACL from one segment to 




another 


cu_$ 1 evel_get 


obtains current ring validation 




1 evel 


cu__$ 1 evel_set 


sets the ring validation level 


cv_acl_ 


formats a segment ACL entry for 




pr i nt i ng 


cv_di r_a cl__ 


formats a directory ACL entry for 




pr i nt i ng 


cv__di r_mode_ 


converts directory access mode to 




bit form 
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cv_jnode_ 
cv_user i d_ 
get_group__i d_ 
hcs_$add_acl_entr i es 



converts segment access mode to bit 
form 

converts process class identifier 
to normalized form 
returns access control name of 
current user 

adds or changes ACL entries on a 
segment 

hcs_$add_di r_acl_entr i es 

adds or changes ACL entries on a 
di rectory 

hcs_$del ete_acl_entr ies deletes all or part of an ACL 

on a segment 
hcs_$del ete__di r_acl_entr i es 

deletes all or part of an ACL 
on a directory 

returns access control mode for 
a given segment relative to the 
current validation level 
returns all or part of an ACL 
on a segment 

returns all or part of an ACL 
on a di rectory 

replaces one ACL on a segment 
with another 

replaces one ACL on a directory 
with another 



h cs_$ f s_ge t_mo d e 

hcs_$ 1 i st_acl 
hcs_$ 1 i st_di r_acl 
h c s_$ r e p 1 a c e_a c 1 
hcs_$replace__di r__acl 



3) Storage System, Supervisor 
Directories and Segments 



Entries for Manipulating 



Note: some entries come in pairs. The name ending in 
"file" takes a segment name as an argument, while the name 
ending in "seg" takes a segment number instead. 



hcs_$append_branch ) 
hcs_$append_ branchx J 
hcs_$append_J i nk 
hcs_$chname_f i 1 e 1 
hcs_$chname_seg J 
hcs_$del entry_ f i 1 e 1 
hcs_$del entry_seg / 
hcs_$f s_jnove_ f i le 1 
hcs_$f s_move_seg J 
hcs_$make_seg 



creates a segment or a directory 

creates a directory link 

adds, deletes, and changes names 

found in a directory 

deletes a single entry in a 

di rectory 

moves a segment from one directory 
to another 

creates a new segment and then 
initiates it 
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hcs_$s et_.be 1 
h c s_$ s e t _b c_s eg/ 
hcs_$star_ 

hcs_$status_ 

hcs_$ truncate_f i le 



h c s _$ t r u n c a t e_s e g } 
See also 1) Storage System, Utility Routines. 



sets the bit count of a segment 

implements the storage system star 
convent ion 

returns information about a given 
segment 

truncates a segment to a given 
length 



k) Storage System, 
Address Space 



Supervisor Entries for Manipulating an 



h c s_$ f s_g e t_mo d e 

hcs_$ f s get u path name 
h cs_$ f s_ge t_r e f __name 
h c s_$ f s_ge t_s e g_p t r 

hcs_$ i ni t i ate 

hcs_$ i ni t iate_count 
hcs_$make__ptr 

hcs_$termi nate__f i 1 e ? 
hcs_$ termi nate_seg J 
hcs_$termi nate_name 1 
hcs_$ term? nate_noname J 



returns access control mode for 
a given segment relative to the 
current validation level 
returns path name for a segment 
specified by segment number 
returns a reference name for a 
segment specified by segment number 
returns a segment number for a 
segment specified by a reference 
name 

maps a given segment into the 
address space of the current 
process 

same as hcs_$ ? ni t i ate but also 
returns the segment's bit count 
returns a pointer to a segment 

entry point, following search 
rules and link conventions 
removes a segment from the address 
space of the current process 
removes a reference name from the 
table which defines the address space 



See also term_ and 
Ut i 1 i ty Routi nes . 



change_wdir_ under 1) Storage System, 



5) Clock and Timer Services 

clock_ reads calendar clock 

convert^ date__to_ bi nary_ converts ASCII string to binary t 

cpu_t i me_and_pagi ng_ returns CPU time used and paging 

activity for this process 
date_time_ converts binary time to ASCII 

str i ng 



me 
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decode_clock_va1 ue_ 

t i fne r manager 
total _cpu_t ime_ 



returns information about binary 
t ime^ 

ys % v Y i uc^ a i oi in v~ i uurvo 

returns total CPU time used by 
this process 



6) Subroutine Call and Argument Utilities 



These are used 
facilities are 
cal 1 ing sequence. 

cu_$arg_count 

cu_$arg_l i st__ptr 

cu_$arg_ptr 

cu_$arg_j>tr_rel 

cu_$gen_cal 1 
cu_ $ptr_ca 1 1 



cu_$stack_f rame_ptr 

cu_$stack_f rame_s i ze 
decode_descr 1 ptor_ 



See also the MPM 
Cal 1 i ng Sequences. 



in cases where standard PL/ I language 
not adequate/ such as a variable length 



returns number of arguments 
procedure was called with 
returns a pointer to current 
argument list 

returns a pointer to a specified 
argument in current argument list 
returns a pointer to a specified 
argument in a specified argument 
list 

generates a subroutine call to a 
procedure where name and arguments 
are not known at compile time 
generates a subroutine call to a 
procedure whose name is not known 
at compi 1 e t ime 

returns a pointer to the current 
stack frame 

returns current stack frame size 
used to interpret PL/ I argument 
descr i ptors 

Reference Guide section, Subroutine 



7) Command Environment Utility Procedures 



cu_$cl 
cu_$get_cl 
cu_$set_cl 
cu_$cp 

cu__$get_cp 
cu_$set_cp , 



controls which procedure is invoked 
to return to command level following 
quit or unclaimed signal 
controls which procedure is used as 
the command processor 



See also the MPM Reference Guide 
Language Environment. 



section. The Command 



(c) Copyright, 1973, Massachusetts Institute of Technology 

and Honeywell Information Systems Inc. 



2.1 



Subroutine Repertoire 
Programming Environment 
Page 6 



MULTICS PROGRAMMERS' MANUAL 



8) 



9) 



I/O System Facilities 

broadcast^ 

discard.. output.. 

f i1e_ 

ioa_ 
ios_ 

ios__$read_ptr 1 
ios_$wr i te_ptr / 

nstd_ 

plot_ 

read_l i st_ 
syn 
tape_ 
tw_ 

user_i nfo_$ tty_data 
write list 



directs an output stream to several 
other streams 

infinite sink for an output stream 

I/O interface to the Multics 
storage system 

produces formatted printed output 
the complete Multics I/O system 
two special high speed entry points 
for character string I/O to and from 
the typewriter terminal 
nonstandard tape device interface 
modul e 

produces two-dimensional graph for 
a display 

reads and converts free format 
typed input 

makes one stream name equivalent 
to another 

Multics standard tape interface 
modul e 

typewriter device interface module 
returns information about the 
current terminal device 
automatically converts and formats 
output variables 



See also the MPM Reference Guide section/ Input and Output 
Faci 1 i t i es . 



Error Handling Facilities 
act i ve_f nc_err_ 
com__e r r_ 
comma nd_query_ 
condi t ion_ 

f i nd_cond i t i on_J nf o_ 
revers i on_ 
s i gnal__ 



handles errors encountered by 
active functions 

prints a standard status message for 
common errors 

handles questions generated by 
commands 

establishes a procedure to handle 
a named condition 
returns information about a 
condi t ion 

discards a condition handling 
procedure 

calls the handler of a named 
condi t ion 
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unpack_system_code_ converts packed status code into 

standard status code 

See also the MPM Reference Guide section, List of System 
Status Codes and Meanings. 

10) Routines to Convert Some Data Type To and From a Character 
String Representation 

convert__bi nary_i nteger_ converts binary integer to ASCII 

str i ng 

convert_date_to_bi nary_ converts ASCII string to binary clock 

readi ng 

cv_bin_ converts binary integer to ASCII 

str i ng 

cv_dec_ converts ASCII decimal string to 

binary integer 

cv_float__ converts ASCII floating point string 

to binary real 

cv__oct_ converts ASCII octal string to binary 

integer 

date_time_ convert clock reading to ASCII string 

Note: some data type conversion can also be performed 
within the PL/I language. 

See also k) Storage System, Supervisor Entries for 
Manipulating an Address Space, for conversion from 
character string name to pointers in the address space. 

11) Object Segment Manipulation Routines 

adjust_bi t_count_ sets bit count of a segment 

to last nonzero character 

make__obj ect_map_ used by a compiler to put finishing 

touches on a newly created object 
segment 

object_info returns structured information 

about an object segment 

stu_ (Symbol Table Utility) used to 

retrieve information from a 
procedure symbol table 

12) Miscellaneous Procedures 

decipher^. decodes an encoded array of words 

encipher encodes an array of words 
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get_process_i d_ 

hcs_$ block ] 
hcs_$wakeup > 
Jpc_ J 
parse_.fi 1 e_ 
random_ 
unique_bi ts_ 

uni que_chars_ 



user_i nfo_ 



returns identification of current 
process 

interprocess communication 

parses ASCII text into tokens 
random number generator 
returns a bit string different 
from all other such strings 
converts a unique bit string 
to a unique character string 
which contains no vowels 
returns miscellaneous information 
about the current user 
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£RQ6RAMM1NQ LANGUAGES 

A number of programming languages are available on Multics: 
PL/I, FORTRAN, BASIC, ALM, APL, and LISP. ALM is an assembler, 
APL is an interactive interpreter, LISP is both an interactive 
interpreter and compiler, and the rest are compilers. 

BASIC on Multics is the Dartmouth College BASIC language and 
the current compiler is a copy of the one developed by Dartmouth 
College. Multics PL/I is the proposed ANSI standard PL/I, 
Multics FORTRAN is the ANSI standard FORTRAN, and Multics APL is 
identical to the IBM APL. Multics PL/ I uses the full ASCII 
character set. 



PL/ I can be regarded as the standard compiler language on 
Multics. The calling sequences, argument declarations, and 
standard data types in terms of which the system is documented 
are taken from PL/ I. This is because the system itself is 
written largely in PL/ I . In the same sense, ALM is the standard 
system assembler since areas of the system requiring 
assembly-language coding are written in ALM. 



Users of other languages, howev 
difficulties because they choose to wor 
Each Multics translator is callable 
object code segments which are also ca 
program written in one of the Multics 
programs written in the same language by 
language's calling conventions. A more 
ability to call programs written in ano 
some cases one language does not conta 
to construct calls or arguments to progr 
same language. (See Common Features bel 



er, should encounter no 
k in another language, 
as a command and produces 
liable as commands. A 

languages can call other 
merely following that 

troublesome point is the 
ther language since in 
in the mechanics required 
ams not written in the 
ow, number 6.) 



Common Features 

1) A Multics compiler or assembler 
of the form 



is invoked by a command line 



language_name source_name 

and takes as its source code a segment named 
"source__name. 1 anguage_name" . For example, the command line 

pll square_root 

would invoke the PL/ I compiler to compile the source code 
contained in the segment square_root . pi 1 in the user's 
working directory. 
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2) A source code segment must be prepared prior to invoking the 
translator. This is done using a Multics editor such as edm 
or qedx. (See the MPM write-ups for the edm and qedx 
commands.) It is at this point that the source code segment 
is given the appropriate name as described in 1) above. It 
can include instructions to insert the source code contained 
in other segments (known as include files) into this source 
segment at compilation time. 

3) A Multics compiler or assembler produces an object segment 
in the user's working directory. The object segment 
contains the object code produced by translation of the 
source code as well as Multics standard linkage and symbol 
table information. The object segment has the same name as 
the source segment/ minus the language.. name component. 
Continuing the example from 1) above/ the object segment 
square_root would be produced. 

U) The production of compilation and assembly listings is at 
the user's option. If listings are produced they are put in 
the working directory with a name of source_name. 1 1st ; e.g./ 
square_root . list .. 

5) The user can control the verbosity of error messages printed 
on his terminal during a trans Tat ion. See the MPM write-up 
for the translator to be used. 

6) In general/ programs coded in one Multics language are able 
to call programs coded in another Multics language. Any 
exceptions or restrictions (such as the types of arguments 
which may be passed) are noted in the documentation of the 
various languages. 

7) Each Multics language has an MPM write-up describing: the 
command which invokes the translator. It describes how the 
command is used/ including the use of optional features such 
as production of listings and verbosity of error messages. 
This document refers, when necessary/ to a complete language 
description usually found outside the MPM. The command 
write-up itself notes any differences between the standard 
description and the current version. 
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SYSTEM PROGRAMMING STANDARDS 

This section outlines many of the design and coding 
standards followed by Multics system programs. It is provided to 
give users some insights into what is considered to be good 
programming practice on Multics. The information presented below 
represents the accumulation of several years of experience in 
programming on Multics. It is hoped that it will aid users in 
their own programming efforts. As will be obvious, some of the 
standards apply only to modules of the system itself. On the 
other hand / those standards may suggest analogous procedures 
which would be appliable to other programming projects. 

Coding Standards 

1) All system subroutines must be pure, so that a single copy 
may be shared by all users. The Multics PL/ I and FORTRAN 
compilers produce only pure subroutines. 

2) All system subroutines must be written in the PL/ I language. 

Explicit permission of the project management is required to 
use any other language. To aid others in understanding a 
program, the program listing should be well commented. This 
includes explaining the meaning of important variables. 

3) Only subroutines documented as part of the Multics system 
(not including tools and the author-maintained library) may 
be called. 

h) The names of all system programs that are not commands or 
active functions must end with an underscore (__) . The names 
of all temporary segments and all I/O streams and condition 
names (other than PL/i defined condition names) used by 
system modules must also end in an underscore. This is to 
avoid naming conflicts with the user. 

5) All variables used, including called subroutines, must be 
declared. This is done to increase program readability and 
reduce the confusion introduced by default or implicit 
declarations. For called subroutines, the parameter list 
must be fully declared, unless, of course, the subroutine 
accepts a variable number of arguments (e.g., a free format 
output subroutine). For readability, declarations should be 
collected together in a logical way (e.g., at the beginning 
of the subroutine or block for which they apply, or at the 
end) rather than being scattered throughout the program. 

6) The use of pointers as arguments should be avoided when 
practical. Passing a data item as an argument rather than a 
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pointer to that item makes a program less error prone since 
the compiler can make checks for argument mismatch and since 
it is sometimes possible to perform run-time argument 
val idation. 

7) Special characters should be placed in the program directly. 
To lessen dependencies on the character code being used/ the 
built-in function unspec should not be used for this purpose. 
For example, 

declare nl (char(l) initial (" 

"); 

declares "nl" to be a one-character string whose value is 
the new line character. The statement 

unspec(nl) ="000001010"b; 

should not be used. 

8) Use of implicit conversion from one data type to another is 
prohibited, since it makes a program harder to understand. 
For example, 

declare x fixed bin(18), y bit(18); 

y=x; 

should not be used. Instead one should write 
y=bi t(x/18); 

9) Use of external static variables which do not contain a 
dollar sign (e.g./ declare x external static) is prohibited 
since this data type is not efficiently implemented in the 
current Multics environment. External references of the form 
a$b are allowed. If the programmer needs to have an external 
data base which is shared among many subroutines/ he may 
either create a segment by an appropriate storage system call 
and reference it using based structures or use the assembler 
to create a data segment by appropriate use of the segdef 
pseudooperat i on . The programmer wishing to do this should 
consult with a knowledgeable member of the Multics 
Development Group. 

10) All variables should be of the automatic storage class unless 
there is a good reason for them to be internal static; i.e./ 
they are static by nature. See also rule 11 below. 
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11) In PL/ 1 programs/ to avoid having to initialize variables 
whose values are constant every time the subroutine 
containing them is entered/ and to avoid having copies of 
these variables made for every user of the subroutine/ one 
should use internal static and initialize the variables using 
the initial attribute. The PL/ I compiler will allocate space 
for these variables in the text section of the subroutine 
being compiled and will initialize them. Since the text 
section is pure/ one copy of these variables will be used by 
all users of the subroutine. Unfortunately/ if a variable of 
this type is passed as a argument to another subroutine/ the 
compiler has no way of knowing whether or not that variable 
is to be changed by that subroutine and it/ therefore/ puts 
the variable into the linkage section. Therefore/ if one has 
a large number of "constant" variables that are also passed 
as parameters/ one should put them in the text portion of an 
assembly language program and initialize them using the 
appropriate data generating pseudooperat i ons and reference 
them using either based structures or the "a$b" notation. 
This will assure that only one copy of these variables is 
used by all users of the subroutine. The programmer wishing 
more clarification of this point should consult with a 
knowledgeable member of the Multics Development Group. 

12) Use of the PL/ I al locate and free statements should be 
cleared in advance with project management/ since there often 
exist more efficient ways to accomplish the same task. 
Subroutines that do perform allocations (or call subroutines 
which do) must establish a cleanup procedure to free the 
storage in the event that processing is aborted. 

13) When possible/ the PL/ I on, revert and signal statements 
should be used instead of the condition_/ reversion^ and 
signal_ subroutines since they are more efficient and make 
the program less system dependent. 



Ik) The programmer should avoid writing PL/ I functions with 

multiple entry points which return different data types 

unless there is a good reason to do so, since this generates 
extra code at each return statement. 
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Programmi ng Stvl e 

1) The most common route through a program should be the most 
efficient. More exotic facilities which are inherently 
expensive should be separated from the simple facilities so 
that a casual user need not pay for the exotic each time he 
uses the simple. 

2) System programs should/ in general, use one of the three 
standard I/O streams: user_input, user_ output, and 
er ror_output . Only special I/O service programs should issue 
I/O attach or detach calls for these streams. Commands should 
not, in general, provide optional off-line output. The 
file_output command is provided for this purpose. 

3) All programs that are not commands or active functions should 
return a status code indicating successful completion or 
occurrence of an unexpected event, unless they are programs 
for which errors are unrecoverable or extremely rare; e.g., 
console output subroutines. This type of program should make 
use of the Multics signalling facility to signal that 
one- i n-a-mi 1 1 i on error. In general, because of the higher 
overhead involved, programs should not make use of the Multics 
signalling facility for routine errors and status conditions. 
Subroutines which are directly called by the user must return 
only standard error__tabl e_ codes. See the MPM Reference Guide 
section. Strategies for Handling Unusual Occurrences. 

k) In most cases, programs that are not commands or active 
functions should not print error messages, but should allow a 
higher level subroutine to decide on the seriousness of errors 
and what to do about them. In general, it is wise to let the 
most qualified subroutine give the message. A good rule of 
thumb for determining the most qualified subroutine is to ask 
whether anything could be learned by reflecting the error to a 
higher level subroutine. If the answer is no, then the most 
qualified subroutine has been found. 

5) All programs that are not commands, active functions or gates 
into a ring should assume they are called with the correct 
number and type of arguments and should not make checks. This 
is to avoid continually paying the cost of argument checking 
in programs which call the subroutines correctly. This does 
mean that the programmer must be careful to call subroutines 
cor recti y. 

6) System programs should be prepared to execute properly even if 
they did not complete execution during a previous invocation 
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8) 



9) 



because of a quit or a fault. That is, they should either 
operate normally or warn the user of the consequences of 
continuing. For example, edm warns the user that, if he 
continues, the partically completed results of an earlier 
invocation will be lost. 



7) System programs should never call a command if 
subroutine which does almost the same thing, 
inherently more expensive since they are designed 
directly with a human user. 



there is a 
Commands are 
to interact 



System programs should not use a subroutine to do something 
which can be done reasonably easily in a few PL/ I statements. 
The purpose of this rule is to avoid the proliferation of 
unnecessary system subroutines. The exceptions to this rule 
are input/output (see paragraph 1 under Error Hand! i ng and I /Q 
below) and conversion from character to numeric data types. 
The reason for the latter exception is that this type of 
conversion is inherently more expensive than calling a 
specialized subroutine. 



Calls to subroutines which require 
minimized when this does not conflict 
or degrade the user interface. This 
overhead involved in setting up 



descriptors should be 
with program readability 
is because of the higher 

argument lists with 



descriptors. For example, one should try to minimize the 
number of ioa_ calls in a program. This should not be 
interpreted to mean that one should remove all error messages 
from his program or make their output so terse as to be 
unreadable. It simply means that if, subject to the 
constraints mentioned above, it is possible to use one ioa_ 
call rather than two then the programmer should to so. 

Data Ease Management 

Designing a program for a virtual memory environment 
requires a new outlook on program and data organization. Though 
the programmer is freed from the onerous task of allocating 
physical storage for his programs and data (e.g., storing 
intermediate results on secondary storage, overlaying parts of 
his programs with others to fit into core memory, etc.) he cannot 
ignore the issues of data management and program organization if 
he wants his program to be reasonably efficient. This is 
especially true for programs which manipulate large amounts of 
data. The attitude that an infinite virtual memory is available 
and if a program needs more room it can create another segment, 
may be all right for the casual user building a one-shot program 
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but not for the systems programmer. A major aim of the 
programmer should be to minimize the working set of his programs; 
i.e./ his programs should create as few segments as is practical/ 
reuse the ones they do create and should avoid unnecessary 
moving of data. The term working set is used loosely here to 
denote both the number of segments and the number of pages in the 
execution path of a program. In Multics it generally pays to 
spend CPU time (within reason) to save space. This principle 
should not/ of course/ be taken to an extreme. It does not mean, 
for instance/ that one should not use a hash table. It is true 
that a hash table takes up more space than an equivalent linear 
list but a program will take fewer page faults referencing the 
former than searching the latter. In this case, the actual 
working set of the former is smaller even though its potential 
working set is larger. In all cases, the programmer must 
exercise his judgement as to the proper tradeoff between working 
set size and CPU usage, always avoiding the temptation to allow 
his working set to expand to infinity. 

In addition to this basic principle/ the following 
gu i del i nes appl y : 

1) System programs must leave their data bases in a consistent 
state; e.g./ a program which changes the contents of a segment 
should reset the bit count of that segment when it is 
finished. Programs should make any period of inconsistency as 
short as possible. They must also clean up after themselves; 
e.g./ free storage should be released. 

2) In order to assure consistent behavior/ all standard 
translators must use the subroutine tssi__ to interface with 
the storage system. It might not make sense for nonstandard 
translators such as BASIC to use tssi_. Exceptions of this 
sort should be cleared in advance with the project management. 

3) System programs should initiate the segments they access by a 
null reference name and should subsequently access those 
segments via a pointer. In general/ segments initiated by a 
module should be terminated by that module (see point k 
below) . 

4) In general, the process directory should be used to hold 
temporary segments. If a program is not being entered 
recursively it should create temporary segments with 
intelligible names (e.g./ containing the name of the creating 
program). It should clean up after itself before exiting by 
either truncating or deleting these temporaries. If the 
temporary segment can be reused the next time the program is 
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invoked it should be truncated; otherwise, it should be 
deleted. If a program is being entered recursively (e.g., one 
quits out of a command, issues a hold command, and reenters 
that command), it should create temporary segments whose names 
consist of a unique first component followed by one or more 
intelligible components. These segments should be deleted 
when the program exits. If, for some reason, a program cannot 
be made recursive it should detect the fact that it is being 
entered recursively, warn the user that partially completed 
work of an earlier invocation will be lost if he continues, 
then give him the option of continuing or exiting. Programs 
which create temporary segments should establish cleanup 
procedures to truncate or delete these segments if execution 
is abnormally terminated. As mentioned above, the names of 
temporary segments must end in an underscore. 

5) Any system program which creates new segments (other than 
temporary segments) should put them into the user's current 
working directory unless the program explicitly makes 
provision for the user to provide a target directory. (The 
move and copy commands fall into this latter category.) The 
aim of this rule is to avoid messing up another directory, 
such as the directory from which a source segment was 
obtai ned. 

6) System programs which create new segments must set access 
control lists according to the conventions enumerated below. 
If a segment is being replaced instead of being newly 
created, the command must leave the access control list as it 
was before the command acted. For instance, a translator 
finds that an object segment already exists with read and 
execute access for this user, and with other access for other 
users. The translator must obviously add write access to 
change the segment contents, but should restore the entire 
access control list to its former value when the translation 
is completed. The storage system interface subroutine tssi_ 
does this automatically for the translator writer. The access 
to be given to the user creating a segment is: 

segment Type Access Ring. BracKets 

directory segment SAM v,v 

object segment RE v,v,v 

data segment RW v,v,v 

where v is the current validation level of the user. See the 
MPM Subsystem Writers' Guide section, Intraprocess Access 



(c) Copyright, 1972, Massachusetts Institute of Technology 
All rights reserved. 



2.5 



System Programming Standards 
Programming Environment 
Page 8 



MULT ICS PROGRAMMERS 1 MANUAL 



Control (Rings), for a discussion of validation level. 
Addi tional Standards io_r_ Commands M Subsystems 

Through the mechanism of the command processor any program 
system subroutine, system command, user subroutine can be 
invoked from the console. System commands are a special class of 
subroutines that are explicitly programmed with the console user 
in mind. They must check carefully for argument validity; they 
must warn the user of possible misunderstandings; they must be 
very reliable. They must, to the greatest possible extent, be a 
self-consistent set; i.e., the behavior of a command should be 
predictable from that of other commands. 

For these reasons a number of additional standards are 
necessary for system commands and subsystems. 

Namins Conventions 

1) For ease of typing, all commands must have an abbreviated 
name consisting of the first letter of the first two or three 
syllables or first two or three words of its name (e.g., 
rename rn, unlink ul, pr i nt_attach_tab 1 e pat). 

2) All command names and abbreviations must be cleared in 
advance with the project management. 

prpgremmjnfl Style aM User interface 

1) if a command would also be useful as a subroutine, break it 
apart into a command which interfaces with the user 
(processes multiple arguments, handles the star and equals 
conventions, interprets control arguments, etc.) and a 
subroutine which does the work. This subroutine, like all 
subroutines, should return a status code rather than printing 
an error message. The outputing of error messages like all 
other user interface problems should be handled by the 
command. 

2) Any command for which the star convention makes sense should 
use the star convention. Any command for which the equals 
convention makes sense should use the equals convention. See 
the MPM Reference Guide section, Contructing and Interpreting 
Names for a discussion of the star and equals conventions. 

3) Characters which have special meanings to commands (e.g., 
"*", "=", ">" »<») should not be used in any context other 
than their standard one. For example, a command should not 
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interpret an argument of "* n as meaning that user wants to be 
logged out. 



k) Commands should not be too powerful, that is, typing errors 
should not cause disastrous results. For example, with the 
old remove command 



remove a>b 



would delete the segment b in directory a, whereas 
remove a> b 



(i.e., one accidentally types a space before the b) would 
delete the directory a. To remedy this, there are now two 
commands: delete which deletes only nondi rectory branches, 
and deletedir which deletes only directory branches. 



5) Unless the purpose of a command is to produce some sort of 
output, it should produce no output during normal operation; 
i.e., it does not need to tell the user that it is doing its 
job. For example, if one enters the command 



delete x y 



the delete command produces output only if it has trouble 
deleting x or y. It does not type "deleting segment x", 
"deleting segment y". Commands which take a long time to 
execute (e.g., pll) should print a short message when they 

are entered to indicated they are functioning. The general 
idea here is to reassure the user that he has not done 
something wrong. After more than a couple of seconds wait, 
the user, particularly a novice user, begins to worry that 
perhaps the computer is waiting for him. 

6) Commands which take segment names as arguments should accept 
pathnames, not reference names, unless they explicitly deal 
with reference names (e.g., termi nate_ref name) . The user who 
has a reference name he wishes to pass to a command may use 
the get__pathname active function to convert this reference 
name to a pathname (e.g., 



status [get__pathname x] 



will cause the status command to be called with the pathname 
of the segment whose reference name is x). See the MPM 
Reference Guide section, Constructing and Interpreting Names 
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for a discussion of reference names. 

7) Commands which interact with the typist should be prepared to 
handle the program_i nter rupt condition which is signalled by 
the program_i nterrupt command. Handling this condition 
correctly is quite tricky. See the MPM Reference Guide 
section/ List of System Conditions and Default Handlers for 
detai 1 s . 

8) When a command which interacts with the typist produces an 
error message which the typist may not have expected/ the 
command should normally follow the error message with a call 
to ios_$resetread (which discards all input read but not yet 
used) on the I/O stream from which it reads input so that the 
typist can modify his subsequent input. 

9) We come now to a standard that is difficult to express with 
any degree of exactness. The phrase "commands should be 
designed with the user in mind" expresses the spirit of the 
standard. What follows is a series of examples designed to 
sensitize the reader to some of the issues involved in 
designing a command. Calling sequences should be logical 
(e.g./ the user should not have to remember that % as a third 
argument to the xyz command causes all segments with a second 
component name fred to be deleted/ whereas a ? in the same 
position suppresses this feature). Commands should allow the 
user to decide whether a protected segment should be deleted/ 
rather than forcing him to make the segment deletable and to 
resubmit the delete request (or worse/ delete the segment 
without warning). Judicious use of red console output is 
encouraged. It should be used to call attention to important 
or unusual occurrences. Remember/ over-use destroys the 
whole purpose of red output — a command which outputs 
everything in red may as well output everything in black. 
Canned messages printed by commands should not contain 
characters which come out as escape characters on IBM model 
1050 and model 2741 consoles and on model 37 teletypes (e.g./ 
"£<segment<:> not found" is not an acceptable message). 

Arsvimem Handl ins 

1) Commands/ wherever possible/ must accept path names (not just 
entry names) as arguments. The subroutine expand_path_ 
should be called to convert a relative path name into an 
absolute path name. 

2) Commands which deal with segments whose names have a fixed 
suffix should not force the user to type that suffix. 
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kather, they should append that suffix to their arguments if 
it is not given. For example/ the command lines 

pll x 

and 

pll x.pll 

should be equivalent. 

3) Commands whose interface is simple (such as the delete and 
addname commands) should accept multiple arguments if It 
makes sense to do so. 

k) All commands which accept a variable number of arguments 
should declare themselves as having no arguments (i.e./ 
comma nd__name: proc;) and should obtain their arguments using 
the procedure cu_$arg_ptr . 

5) Commands must obey Multics control argument conventions as 
described in the MPM Reference Guide section/ List of Command 
Control Arguments. 

C) In general/ for the convenience of the user, command 
arguments should be order independent unless the order 
dependency serves a useful purpose (as in the -ag control 
argument of the enter__abs_reques t command). 

Error tientil infi £&4 HQ. 

1) The input/output facilities of the PL/ I language must not be 
used in system programs since they are more expensive than 
system-provided subroutines. 

2) To read a line from the input stream user_input/ use the 
subroutine ios_$read_ptr . To read a line with appropriate 
data type conversion (i.e./ the user is typing in pointers/ 
floating point numbers / etc.) use the subroutine read_list_. 

3) Output lines fall into three distinct classes: 

a) unusual status messages 

b) questions 

c) everything else 
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Lines of type a) should be output using the subroutines 
com_err_ and act i ve_f nc_err_ (active functions should use 
act i ve_f nc_er r_, all other modules should use com_err_). 
Lines of type b) should use the subroutine comma nd_query_. 
These three subroutines are provided in order to centralize 
the processing of lines of type a) and b) so that changes in 
system conventions in this area may easily be made. For 
lines of type c) the subroutine ios_ should be used when it 
is necessary to format an output line; otherwise, use the 
subroutine i os__$wr i te_ptr . 

k) Commands should check for status codes which have special 

meaning to them and either print appropriate error messages 

or, if the error is easily recoverable, allow for user 

intervention using comma nd_query_. All such messages must 

contain the name of the command which generated them, since 

otherwise the user woulu have no way of knowing which command 

generated a given message if he has issued several at once or 
was running an exec_com segment. Complex programs such as 

compilers may output diagnostics by standard output 
subroutines but should have at least one call to com_err_ to 
notify the system that an error has occurred. 
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Two types of clocks are available on Multics: a real-time 
clock for the entire system and a process execution meter for 
each process. The real-time clock, a hardware calendar clock 
accessible via a special register on a memory controller/ runs 
whenever the system is in operation. It contains a double-word 
integer that is incremented once per microsecond and represents 
the number of microseconds elapsed since January 1, 1901, 0000 
hrs. GMT. An interrupt mechanism is associated with the calender 
clock so that a specified process can receive an interprocess 
wakeup when the calendar clock reaches a specified clock value. 
The specified clock value is regularly compared with the calendar 
clock value/ and when the two are equal an interprocess wakeup is 
generated for the appropriate process. 

A process execution meter is maintained as part of the state 
of each process. It counts the microseconds during which the 
process is running. This meter is used to record each process's 
usage of system resources as well as being available to the user 
to cause wakeups after a specified amount of time has passed. 
There are actually two such meters for each process; the more 
valuable one measures virtual time, which is the time during 
which the process is running decremented by the time it handles 
interrupts and page faults. 



An interrupt mechanism associated with the virtual time 
meter allows a process to receive an interprocess wakeup when the 
meter is incremented beyond a specified value. This meter is 
compared to the specified value at regular intervals and when the 
value is exceeded an interprocess wakeup is generated for the 
running process. 

The uses to which clocks are put are diverse. There are a 
number of general uses for which they can be used. Included are 
the fol lowing: 

1) Resource monitoring and accounting; 

2) Labeling data (e.g., storage system entries) with dates and 
times of interest; 



3) Computing the date and time for output; 
h) Generating a unique bit string; 



5) Waking up a specified process at a specified time/ perhaps 
causing a specified procedure to be called; 
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6) Interrupting a process after a specified amount of CPU time 
has elapsed. 

Access la System Clocks 

A number of commands and subroutines (all described in MPM 
write-ups) permit the user to inspect the real-time clock and the 
process execution meter. The clocks subroutine reads the 
real-time clock and returns its current value as a fixed bin(71) 
quantity. This clock time can be converted to a more 
understandable form using either date_time_ (which returns a 
single character string) or decode_clock_val ue_ (which returns 
the various components of the time -- month / year, etc. — as 
distinct variables. The convert_date_to__bi nary_ subroutine 
accepts a character string like that produced by date__time_ and 
returns a fixed bin(71) equivalent. 

The value of the process execution meter is returned by both 
cpu_time_and_paging__ and total _cpu_t ime_. The resource_usage 
command prints a report of the resources used by the user from 
the beginning of the current month to the time of creation of the 
user's current process. 

The status command and the hcs__$status_ subroutine both 
provide dates and times associated with storage system entries, 
such as the date and time modified and the date and time last 
used. 

The unique_bits_ subroutine returns a bit string generated 
partly from the current real-time clock reading that is 
guaranteed to be unique among all bit strings so generated. The 
un i que_chars_ subroutine converts this value into a character 
string that is also guaranteed to be unique among all character 
strings so generated. 

Facilities fox IlmstA Wekeups 

The interprocess communication facility (described in the 
MPM Subsystem Wr iters' Guide under ipc_ ) allows a user to set up 
channels for sending interrupts (wakeups) to a specified process. 
The interrupt can merely cause that process to return from the 
blocked state to whatever it was previously doing, or can cause 
same other procedure to be called in that process as a result. 
One possible use of this facility is to wake up a process as the 
result of some clock activity. The t imerj manager., subroutine 
(described in an MPM subroutine write-up) provides the necessary 
interface. Using it, a user can specify an event channel for his 
own or another process, whether the process should merely be 
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wakened or a specified procedure should be called / and the nature 
of the clock activity that triggers the wakeup (i.e./ real or CPU 
time). !n specifying the time, the user can further specify 
absolute or relative time/ and can use seconds or microseconds. 
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THE STORAGE SYSTFM DIRECTORY H 1 FRARCHY 

The Multics storage system is used for supervisor segments 
as well as for user segments. Since a single directory hierarchy 
is used for both. It is frequently useful to know the relative 
arrangement of items within the hierarchy. This section outlines 
briefly the organization and contents of the directory hierarchy. 

General ly, the user should never embed pathnames of 
supervisor segments in his programs. Most often, he will use 
these segments indirectly, by invoking some library procedure or 
command that knows both the pathnames and the format of the data 
stored there. The details provided here are intended as 
background information for understanding and, occasionally, 
debugging. The structure described here changes fairly often, so 
it should not be assumed when writing programs. 

Figure 1 is a diagram of the top of the directory hierarchy. 
The name of the root directory is, by convention, omitted from 
pathnames * The diagram shows seven directories always found in 
the root. (Only the basic structure assumed by the Multics 
supervisor is illustrated. Additional segments and directories 
can also appear at all levels in the directory hierarchy.) 

1) system__control_di r 

This directory is the storage location for most system 
accounting, authorization, and logging information. The 
table printed by the who command, the message of the day, 
and the absentee queue segments are the only generally 
accessible segments in this directory. Project 

administration tables are stored in a directory tree that 
starts in system_contro1_di r . 

2) processed i r_di r 

This directory contains one directory for every process 
currently in the system. The name of an individual process 
directory is derived from the unique identification of the 
process. The process directory is used as a place to store 
all segments that are intended to have a lifetime no greater 
than that of the process that creates or uses them. Thus, 
if a compiler needs a scratch area, it can create a segment 
here. A program wishing to create or use a segment in the 
process directory does not normally need to know or 
construct the full pathname of the directory, since the most 
common means of creating a segment uses the process 
directory by default. 
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Five segments are normally placed in a process directory 
upon creation of the process. Others can be added by various 
commands or user programs. The five initial segments are: 



(Process Data Segment) A supervisor 
data base containing the state of the 
process with respect to the 
supervisor. (This segment is 
accessible only to the supervisor.) 

(Known Segment Table) A supervisor 
data base detailing the 

correspondence between segment 
numbers and segment names / as known 
in this process. (This segment is 
accessible only to the supervisor.) 

(Process Initialization Table) A 
driving table used to contain details 
on how the process should initialize 
itself. The name of the initial 
program to be called in this process 
is found in the pit. 

stacks This segment is the stack used for 

PL/ I automatic variables and for 

subroutine call and return 

operations. There is one stack 

segment for each active ring; the 

last character of the stack name is 

the ring number .except in. ring 0, 
where pas is used as a stack. 

combi ned_l i nkage_4. 00 This segment/ managed by the linker/ 

contains i nter procedure links and 
PL/I internal static storage. If the 

total requirements for linkage and 
static storage of a process exceed 
the space available in a segment/ 
additional segments are automatically 
created using the same name; the last 
two characters are a sequence number. 
In addition/ each active ring except 
ring 0 has its own linkage; the 
character before the period in the 
segment name indicates the ring 
number . 



pds 



kst 



Pit 
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Other segments commonly found in the process directory 
include the free storage area used to implement PL/I allocate and 
free statements, temporary storage areas of the editor commands, 
and segments used to contain the parse tree of the PL/ I compiler. 
These segments are created only when needed by the various 
commands and subroutines using them. 

3 ) da emon_d i r__d i r 

This directory contains segments and directories used to 
support the various system daemon processes, such as 
automatic file backup and bulk (card and printer) input and 
output. Except for the queues of the I/O facilities, the 
contents of daemon_di r_di r are not generally accessible to 
users . 

k) user_dir_dir 

This directory is the base of a tree containing all of the 
personal segments of individual users. The immediate 
contents of user_di r_di r is a set of directories, one for 
each project that uses Multics. Contained in a project 
directory is usually one personal directory for each user 
working on that project. 

5) system_l i brary_standard 

This directory contains the library of commands and 
subroutines provided as part of Multics. These procedures 

are documented in the Commands and Subroutine Calls sections 
of the MPM Reference Guide. Unless the user specifies 
otherwise, this directory is included in the list of 
directories to be searched when dynamic linking occurs. 

6) system_l i brary_languages 

This directory contains the processors for all the 
programming languages supported on multics. 

7) system_l i brary_auth_ma i nt 

This directory is similar to sys tem__l i brary__standard except 
that it contains commands and subroutines provided by 
programmers of the local installation. It is distinct from 
system_l i brary_standard so that it can be left out of the 
search path if desired. 
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THE SYS 1 EM L i BRARi FS AND SEARCH RULES 

External references to procedures and data segments are 
bound at execution time by the dynamic linker. (External 
references include both subroutine calls and use of external 
static variables of the form alpha$beta.) The linker uses a 
standard set of rules in searching for the target of an external 
reference. The default search rules are given below. If 
appropriate/ the user can specify his own set of search rules. 
See the write-ups of the set_search_di rs and the set_search_rul es 
commands . 

If neither of those commands have been used/ the search for 
a segment with the same name as the external reference name 
proceeds as follows: 

1) already initiated segments 

This is a list of names that have been previously referred to 
in this process. A reference name is associated with a 
segment by: 

a) use in a dynamically linked external reference from a 
program; 

b) a call (which may be made by the initiate command) 
to hcs_$ i ni t iate/ hcs_$i ni tiate_ count or hcs_$make_seg 
with the "rname" argument a non-null string; 

c) a call to hcs_$make__ptr . 

2) referencing directory 

This is the directory in which the calling or referencing 
procedure is contained as a segment (not a link). 

3) working directory 

This is the directory that has been specified as the user's 
current working directory. The working directory can be 
changed with the change_wdir command or the change__wdi r__ 
subroutine. The initial working directory is the user's home 
directory. (See the MPM write-up for user__i nfo_. ) 

h) >system_l i brary_standard 

This library contains the Standard Service System modules/ 
the Development System modules/ and the PL/1 System modules. 
It contains most system commands and subroutines. 
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5) >system_l i brary_l 

This library contains a small set of commands and subroutines 
that are reloaded every time the system is reinitialized. 
These include hcs_, ios_, cu__, clock_, com_err__, and 
er ror_tabl e__ . From the user's point of view, there is no 
reason for considering this library to be anything but a 
continuation of sys tem_l i brary_standard . 

6) >sys tem_J i brary_languages 

This library contains the language processors for the 
programming languages supported on Multics. 

7) >sys tenrM i brary_auth_ma i nt 

This library contains the author-maintained and 
installation-maintained libraries. The author-maintained 
library consists of a collection of procedures contributed by 
users at a particular installation. It is maintained for the 
convenience of the local user community/ as an aid in sharing 
of programs. Users of author-maintained procedures should be 
aware of two dangers: 

a) there may have been little or no verification of the 
effectiveness or accuracy of the procedures; 

b) no guarantee is made that the procedures will continue to 
be maintained as the system changes. Users of 
author-maintained language translators should be 
especially wary of this second danger. 

The installation-maintained library contains procedures 
installed and maintained by the local installation. It 
differs from the author-maintained library in that 
verification of accuracy and effectiveness of the procedures 
has been performed by the i nstal lat ion, and the installation 
is committed to maintain the procedures. 

I nclude F i 1 es 

Several of the languages on Multics permit the inclusion of 

the contents of a separate segment into a specified place In a 

source segment at translation time. These separate segments are 

known as include files. The translator searches for include 
f i les as fol lows : 
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1) working directory 

See working directory (number 3 above) for a description of 
this directory. 

2 ) >user_di r_di r >proj ect_i d> i ncl ude 

This directory can be maintained if needed by a project for 
use by its members. The directory projected in the path 
name is the name of the user's project. 

3) >1 i brary_di r_di r> i nclude 

This library of source code contains all include files used 
in system programs. 
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SEGMENT. D i RECTORY AND L i NK ATTR i BuTES 

Every directory in the Multics storage system may contain 
three types of entries: segments, d i rector i es, and links. Each 
of these entries includes two types of information: contents (or 
data) and attributes. It is the contents of an entry that is the 
primary purpose for its extence. For a segment/ the contents are 
the data of the segment. For a directory, the contents are the 
entries of the directory. For a link, the contents are the path 
name of the entry to which the link refers. The attributes of an 
entry contain information about the contents of the entry. 

Each entry has a specific set of attributes. A list of the 
different types of attributes that may be associated with each 
type of entry is given below. Each member of the list contains 
the name of the attribute, a list of the types of entries that 
have this attribute, a description of the attribute, and a 
statement of whether or not the attribute may be modified. An 
attribute is explicitly modifiable if there is a storage system 
subroutine that will explicitly change the value of the 
attribute. An attribute is implicitly modifiable if something 
can be done to the entry which will change the value of the 
attribute. An example of the latter is changing the date/time 
modified of a segment by writing into a segment. A description 
of the type of access modes required to modify attributes is 
given in the MPM Reference Guide section Access Control. 

access control list (segments, directories) 

The access control list (ACL) specifies if and how different 
processes may access a segment or directory. ACLs are 
described in detail in the MPM Reference Guide section 
Access Control. An ACL may be explicitly modified. 

author (segments, directories, links) 

The author of an entry is the access identifier of the 
process that created the entry. The author is not 
mod i f i ab 1 e . 

bit count (segments) 

The bit count of a segment specifies the length of the 
contents of the segment in units of bit, i.e., it delimits 
the last meaningful bit of information in the segment. The 
bit count is explicitly modifiable and since it is not 
maintained by the supervisor, should be maintained by all 
procedures that modify the length of the contents of the 
segment. Many system commands and subroutines will not 
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function properly unless the bit count is accurate. The bit 
count is maintained by system procedures that change the 
length of segments. The bit count is necessary because the 
system is unable to automatically maintain the length of a 
segment in units finer than the page size (this measure of 
length is called the current length, see below). In order 
to modify the bit count it is necessary only that the 
process have write access to the segment at the validation 
level, unlike all other segment attributes which require 
modify access in the directory containing the segment. This 
is to insure that any process that can modify the length of 
the segment can also modify its bit count. 

copy switch (segments) 

The copy switch provides a means by which many processes can 
simultaneously execute impure procedures. When a segment 
with the copy switch on is symbolically referenced, either 
by resolving a symbolic link reference or by initiating the 
segment, a pointer to a copy of the segment for this process 
is returned instead of a pointer to the segment itself. In 
this way each process will be using its own copy of the 
segment and will be able to modify the segment without 
affecting other processes. In the current implementation a 
new copy is generated each time a link is resolved to the 
segment by a different name or each time the segment is 
initiated by a different reference name. To avoid 
confusion, it is therefore recommended that a segment with 
the copy switch on have only a single name. The copy switch 
may be explicitly modified. 

current length (segments, directories) 

The current length specifies the length of the contents of 
the segment or directory, i.e., it delimits the last 
non-zero bit of data. It is accurate to units of page size. 
The current length is implicitly modified by storing data 
beyond the previous current length or by truncating the 
segment or directory. 

date/time dumped (segments, directories, links) 

This attribute specifies the last time a backup copy of this 
segment were made by the Multics backup procedures. The 
date/time dumped is implicitly updated by the Multics backup 
procedures when an entry is dumped. 
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date/time entry modified (segments, directories, links) 

I I I I «J U <_ l_ 1 I UUIC J I I I \_ Lilt L. I I I H_ UIIJI V/ I tilt 

this entry were last modified. The date/time entry modified 
is implicitly updated when an entry is modified. 



date/time modified (segments, directories) 



This attribute specifies the time the contents of the entry 
were last modified. The date/time modified is implicitly 
updated when the data of an entry is modified. (For 
implementation reasons the date/time modified may not be 
precisely accurate but will normally be less than a few 
minutes after the correct time.) 



date/time salvaged (directories) 



This attribute specifies the time the directory last had to 
be salvaged. Salvaging implies that the directory had to be 
modified in order to eliminate an inconsistency in its 
contents so that the storage system can function properly. 
The date/time salvaged is implicitly modified when a 
directory is salvaged. 



date/time used (segments, directories, links) 

This attribute specifies the last time the contents of the 
entry were referenced. (For implementation reasons the 
date/time used may not be precisely accurate but will 
normally be less than a few minutes after the correct time.) 

initial access control lists (directories) 



The initial ACL specifies the default value for the ACL of a 
segment or directory newly created in the associated 
directory. A detailed description of initial ACLs is given 
in the MPM Reference Guide section Access Control. The 
initial ACLs may be explicitly modified. Only modify access 
in the directory at the validation level is necessary to 
modify an initial ACL. Unlike most directory attributes, no 
access on the superior directory is necessary. 



(c) Copyright, 1972, Massachusetts Institute of Technology 
All rights reserved. 



3.3 



MULT ICS PROGRAMMERS* MANUAL 



Segment, Directory and Link Attributes 
Storage System 
Page k 



maximum length (segments) 

This attribute specifies the maximum length of the segment/ 
i.e./ the size beyond which the segment may not grow. The 
maximum length is accurate to units of page size. The 
maximum length may be explicitly modified. 

multi-segment file indicator (directories) 

A non-zero value for this attribute indicates that this 
directory is actually a mul ti -segment file. The value of 
the attribute is the number which is the entry name of the 
last segment in the mul t i -segment file. The mul t i -segment 
file indicator is implicitly modified by the mul t i -segment 
file primitives when the length of the file changes. It may 
also be explicitly modified. 

names (segments/ directories/ links) 

The names of an entry are the character strings used to 
identify and reference the entry. Each entry may have many 
names. The first name on an entry is termed the primary 
name and will always be listed first until it is deleted. 
Entry names may be explicitly modified. 

quota (directories) 

The quota of a directory is the number of records of storage 
that segments and directories inferior to this directory may 
occupy/ excluding those subtrees that have their own quota. 
The quota may be explicitly modified. Only modify access in 
the directory at the validation level is necessary to modify 
the quota. Unlike most directory attributes/ no access is 
needed in the containing directory. 

records used (segments/ directories) 

The records used by a segment or directory is the number of 
records of secondary storage occupied by the contents of the 
segment or directory. The records used may be implicitly 
modified by changing the amount of storage occupied by the 
entry. This may be accomplished by changing its length. 
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ring brackets (segments, directories) 

The ring brackets of a segment or directory partially 
specify access to that segment or directory. Ring brackets 
may be explicitly modified. A full description of ring 
brackts is found in the MPM Subsystem Writer's Supplement 
Reference Guide section Intraprocess Access Control (Rings). 

safety switch (segments, directories) 

If the safety switch of a segment or directory is on, that 
segment or directory can not be deleted. The safety switch 
may be explicitly modified. 

secondary storage device identifier (segments, directories) 

This attribute identifies the type of secondary storage 
device on which the contents of this segment or directory 
reside. The secondary storage device identifier is 
implicitly modified when the device upon which the contents 
of the entry reside is changed. 

type (segments, directories, links) 

The type of an entry indicates whether it is a segment, a 
directory, or a link. The type of an entry may not be 
modified. 

unique identifier (segments, directories links) 

Each entry in a Multics storage system hierarchy has a 
distinct unique identifier. This unique identifier may not 
be modified. 

Warning 

The information contained in this MPM section is not fully 
accurate until step 2 of directory reformatting is completed 
(probably about November, 1972). The following attributes will 
not exist until then: initial access control list, maximum 
length, safety switch, and (for directories) ring brackets. 
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ACCESS CONTROL 

Access control is the regulation of the right of a process 
(the acti ye component of the system) to use or reference objects 
within the system. Examples of such objects are typewriters/ 
printers, segments, and processes. This section discusses the 
regulation of the right of processes to use or reference certain 
objects within the Multics storage system, namely directories and 
segments . 

This section is divided into two parts. The first part 
explains what rights may be granted or denied a process 
referencing a segment or directory. The second part describes 
how different access rights may be granted to different 
processes, i.e., interprocess access control. 

A few sentences are in order about the use of this section. 
The access control mechanism represents an attempt to provide a 
general capabilty for controlling access in many different ways 
and yet keep the mechanism simple for common applications. This 
section is a comprehensive description of the full access control 
mechanism and most readers will find much if not all of the 
material of no interest to them. Users who do no sharing of 
segments, i.e. those who have segments which only they reference, 
need not know anything about access control because the system 
defaults automatically provide for this case. Even if the user 
makes use of programs of other users he need not know anything 
about access control because setting access is the responsibility 
of the other users. Only if the user wishes to share his 
segments with other users need he know anything about access 
control. In this case he should first read the MPM Introduction 
Chapter 3, Beginner's Guide to the Use of Multics. That chapter 
provides sufficient information about access control for most 
common applications. Only if that chapter is insufficient for 
the user's needs, should he then read this section. 

Yet another facet of Access Control is described in the MPM 
Subsystem Writers' Supplement section I ntraprocess Access Control 
( Ri n£S ) . This part of access control differentiates between the 
access rights that a process may be granted in different states. 
It is called the ring mechanism, and is of use to the subsystem 
writer who wishes to write a protected subsystem. 

Part 1: Access Mooes 

One does not simply want to regulate whether or not a 
process can reference a given object, but usually wants a finer 
control in order to regulate various ways in which a process may 
use an object. For different types of objects the means of 
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referencing may be different. For segments and directories these 
ways of referencing objects are termed modes of access or access 
modes. Since segments and directories are different types of 
objects/ having different properties and different operations for 
referencing them/ they have different modes. 

Segment access modes determine the ways in which a process 
may reference the data of a segment. Directory access modes 
determine the ways in which a process may reference the 
attributes of directory entries. Each mode is labelled by a 
distinct/ single character identifier that is used when 
specifying the mode to system commands. 

The access modes for segments are: 

execute (e) an executing procedure may transfer to this segment 
and words of this segment may then be interpreted as 
instructions and executed by a processor; 

read (r) the process may execute instructions that cause data 

to be fetched (loaded) from the segment; 

write (w) the process may execute instructions that cause data 
in the segment to be modified. * 



The access modes for directories are: 



status (s) 



the attributes of segments/ directories and links 
contained in the directory and certain attributes of 
the directory itself may be obtained by the process 
(see the MPM Reference Guide section on Segment/ 
Directory and Link Attributes for a definition of 
attributes); 



modify (m) 



directories and 
and certain 



the attributes of existing segments/ 
links contained in the directory 
attributes of the directory itself may be modified; 
and existing segments/ directories/ and links 
contained in the directory may be deleted; 



append (a) 



new segments, directories and links may 
in the directory. 



be created 



If a segment or directory is not accessible in any of the 
above modes then the process has no access to the segment. 



* Until step 3 of directory reformatting has been completed (probably about 
February. 1973). the segment access mode append (a) should appear on segment 
ACLs that have write (w) access mode. 
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Part 2: I nterorocess Access Control 

In order to be able to grant different processes distinct 
access rights it is necessary to be able to distinguish different 
processes. For this purpose, each process has an associated 
access identifier. The access identifier is fixed for the life 
of the process. The identifier is a three component character 
string with the components separated by periods (.). The first 
component is the name of the person on whose behalf the process 
was created. The second component is the name of the project 
group of which the person named in the first component is a 
member. This person-project combination is termed a user. The 
same person may log into Multics under different projects and is 
considered to be two different users. The third component of the 
access identifier is the instance which is a single character 
used to distinguish different processes belonging to the same 
user. The access identifier must be less than 33 characters in 
length. The access identifier Jones . Facul ty , a would be 
associated with a process created for Jones in the Faculty 
project. The "a" instance distinguishes the process from another 
process created for Jones . Facul ty which might have an access 
identifier Jones . Facul ty . b. All processes need not have distinct 
access identifiers. It is quite likely that several processes 
have the access identifier Jones . Facul ty. a which simply means 
that all these processes have the same access rights to segments 
and directories in the storage system. 

Access Control List 

The rights that different process have when referencing a 
segment or directory are specified as an attribute of that 
segment or directory in the form of a list called the Access 
Control List ( ACL ) . Each entry of the list specifies a set of 
processes (actually a set of access identifiers of processes) and 
the access modes that members of that set may use when 
referencing the segment or directory. The modes read, write, and 
execute may be specified in ACLs of segments and the modes 
status, modify, and append may be specified in ACLs of 
directories. On directory ACLs, modify mode may not appear 
without status mode. If some of these access modes are not 
granted in a ACL entry, then processes specified in the entry 
cannot access the segment or directory in the ungranted mode. 
For example, if the ACL of a segment contains an entry for a 
process and the modes specified are read and execute then the 
given process may execute instructions that fetch data from the 
segment, and transfer to and execute instructions in the segment, 
but it may not modify data in the segment. 
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The members of the set of processes associated with an ACL 
entry are specified by a character string called a process class 
identifier. The process class identifier is similar in 
appearance to an access identifier. In fact a string which is an 
access identifier may also be a process class identifier. Such a 
process class identifier identifies the class of processes whose 
access identifiers are the same as the process class identifier; 
e.g./ the process class identifier Jones. Facul ty.a identifies the 
class containing all processes with access identifier 
Jones. Facul ty.a. 

It is very useful to identify larger groups of processes 
than simply those with the same access identifier. This may be 
accomplished by replacing one or more of the three components of 
the process class identifier (i.e./ the person name, project 
name/ or instance) by the asterisk character (*). Such a 
character string identifies that class of processes whose access 
identifiers match the remaining components of the character 
string; i.e./ those components of the string that are not the 
asterisk character. For example/ the class identifier Jones.*. a 
identifies that class of processes with an access identifier 
containing Jones as the person identifier and "a" as the 
instance. Any project identifier in the access identifier will 
match. Therefore/ processes with access identifiers 

Jones .Work. a, Jones . Lazy . a, and Jones . Facu 1 ty . a will be members 
of the class identified by Jones.*. a. Similarly/ processes with 
access identifiers Jones . Lazy . a, Jones. Work. q, and 

Jones . Facul ty.q are members of the class identified by Jones.*.*. 
The string *.*.* identifies the class of all processes. 

structure o_f an Access Control list 

From the above discussion one can see that it is quite 
possible for a single process to be a member of more than one 
process class. This situation can lead to ambiguities on ACLs 
when more than one entry can apply to the same process. To 
eliminate this ambiguity and make ACLs more easily readable/ four 
conventions are imposed on ACLs and their interpretation. First/ 
no process class identifier may appear more than once on any ACL. 
Second/ the ACL is ordered as explained below. Third/ the entry 
that applies to a given process is the first entry on the list 
whose process class contains the given process. Finally/ if no 
entry exists on the list for a given process then that process 
has no access to the segment or directory. These conventions 
assure that the access for every process is uniquely specified by 
the ACL. 
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In order to properly generate and modify ACLs it is 
necessary to have some understanding of how they are ordered. 
The ordering is done by leftmost specificity of components of 
process class identifiers. This can be easily explained by a 
simple ordering algorithm and an example. The entries to be 
ordered are first divided into two groups/ those whose first 
(person) component are specific (i.e./ are not asterisk) and 
those whose first component are asterisk. Those with specific 
first component are placed first on the ACL. Within these two 
groups a similar ordering is done by second (project) component 
again with the specific entries being first. This produces four 
groups. Finally/ within each of these four groups a similar 
ordering is done on the third (instance) component to produce 
eight groups. The eight groups resulting will be in the 
fol lowi ng order : 

1) class identifiers with no asterisks 

2) class identifiers with an asterisk in the third component 
onl y 

3) class identifiers with an asterisk in the second component 
only 

k) class identifiers with asterisks in the second and third 
components only 

5) class identifiers with an asterisk in the first component 
onl y 

b) class identifiers with asterisks in the first and third 
components only 

7) class identifiers with asterisks in the first and second 
components only 

8) the class identifier *.*.* 

Within each of these groups the ordering is unimportant 
because a process may belong to only one class in a group. The 
following is a validly ordered ACL: 
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Jones .Work. a r 
Smith. Lazy.* rw 



(1) 
(2) 



Whi te. *.q 
Black.*.* 
*. Facul ty .m 
* .Student.* 
* . Lazy. * 

* .*.b 

* . * . * 



re (3) 
rew (k) 
no access (5) 



re 
r 

rew 
r 



(6) 
(7) 
(8) 
(9) 



In the above 
Smith. Lazy. h would 
derived from entry 
Jones. Lazy. h would be 
from entry (7), 
Smi th. Facul ty.q would 
entry (9). Note that 



example a process with access 
be able to read and write the 
(2), a process with access 
able only to read the segment 
and a process with access 



i denti f i er 
segment as 

i denti f i er 
as derived 

identi f i er 



be able to read the segment asjderived from 
despite entry (9)/ which apparently grants 
read access to all processes, Smi th . Facul ty. m has no access since 
entry (5) is encountered first. 



Maintenance of Access Control Lists 

Both commands and subroutines are provided for the purpose 
of creating and modifying ACLs. The commands are listacl, 
setacl, and deleteacl (see the MPM write-ups for these commands). 
The subroutines are hcs_$add_acl__entr ies, 

hcs_$add_di r_acl_ent r i es, hcs_$repl ace_acl , hcs__$ repl ace__d i r_acl, 
hcs_$del ete_acl_en tr i es, hcs__$del ete_d i r_acl_entr i es , 

hcs_$l i st_acl , and hcs_$l i st_di r__acl (see the MPM write-ups for 
these subroutines). The specific usage of each of these 
procedures is described in their command and subroutine 
write-ups. The commands and subroutines enforce the constraints 
mentioned above; i.e., they order the ACL and do not permit more 
than one entry with a given process class identifier to appear on 
the ACL. 
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Consider the example of a segment with an ACL containing the 
single entry: 

Jones.*.* r 

A new entry is added for the process class *.Work.* resulting in 
the ACL: 

Jones.*.* r 

*.Work.* rw 

This would superficially appear to given all members of the Work 
project the right to read and write the segment. In actuality it 
gives all members of the Work project the right to read and write 
the segment except for Jones (assuming Jones is a member of the 
Work project). Jones has only read access. If we truly wanted 
to give a l 1 members of the work project write access we would 
have to add another entry to produce: 

Jones. Work.* rw 

Jones.*.* r 

*.Work.* rw 

The entry Jones.*.* is still useful for specifying access for 
Jones when he logs in on any project other than Work. 

It is important to realize that placing a new entry on an 
ACL does not necessarily grant all members of that process class 
the specified access, for some members of that process class may 
also be members of process classes appearing earlier on the ACL. 
The user should, therefore, be aware of what an ACL currently 
contains before modifying it. 

Special Entries ojq. Access Control Lists 

Several Multics system services are performed by special 
processes as opposed to being done in the user f s process. These 
system service processes perform such functions as making backup 
copies of segments in the storage system and queued printing and 
punching of segments at users 1 requests. In order for these 
service processes to perform these functions they must have 
access to the segments to be serviced. In many cases the service 
processes normally service all segments in the storage system 
and, therefore, need access to most segments. These service 
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processes and only these service processes are members of a 
single project called SysDaemon. In order to assure that these 
service processes have access to the segments the storage system 
subroutines automatically place the ACL entry 

♦.SysDaemon.* rw 

on the ACL of every segment, and the ACL entry 

♦.SysDaemon.* sma 

on the ACL of every directory when the segment or directory is 
created or its ACL is entirely replaced. A user taking no 
special action with regard to any members of the SysDaemon 
project will, thereforce, have automatically granted the 
necessary access to all service processes so that they may 
perform their function. 

Under special circumstances, some user may elect not to 
receive the service of a service process on some of his segments. 
To do this, the user simply denies access to his segments to that 
service process by modifying the ACL to contain an entry for that 
service process with null access. It is crucial that a user who 
elects not to receive such a system service be fully aware of the 
nature of the service and the consequences of his choice. For 
example, if the backup processes are not permitted access to a 
segment, backup copies of the segment cannot be made and the 
segment will not survive certain types of system failure. 

PefauU Values for Access Control Lists 

Many system commands and subroutines, e.g., create, 
create_dir, and hcs_$append_b ranch, add an entry for the creating 
process to the ACL of a newly created segment or directory. The 
storage system subroutines also automatically add the above 
mentioned service process entry to all newly created segments and 
directories. It is also useful to be able to specify a list of 
entries to be added to all newly created segments in addition to 
entries for the creating process and the service processes. This 
eliminates the need to expicitly modify an ACL each time a new 
segment or directory is created. This list of entries to be 
added to newly created segments or directories is called an 
initial access control list or initial ACL and is an attribute of 
a directory. Each directory has two sets of initial ACLs, one 
set for segments appended to the directory and one set for 
directories appended to the directory. Since each initial ACL is 
simply a list of ACL entries, it has the appearance of an ACL, 
When a segment or directory is created the service process ACL 
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entry is first placed on the ACL of the segment or directory. 
Then the appropriate initial ACL (i.e., either the one for 
segments or the one for directories) of the containing directory 
is merged with the ACL. The merging of two ACLs means that the 
entries are combined and sorted. If two entries on the resulting 
ACL contain the same process class identifier/ then the entry 
that was originally on the ACL of the segment is deleted leaving 
the newly added entry. In this way the service process entry 
originally on the segment may be overridden by the initial ACL by 
placing an entry with process class identifier * .SysDaemon. * on 
the initial ACL. Finally, any entries specified in the call to 
append the segment (for most system commands this is simply one 
entry for the creating process) are merged into the ACL. Again 
these entries will override the service process and initial ACL 
entries if duplicate process class identifiers exist. 

The default value for the initial ACLs of a newly created 
directory is empty, i.e., there are no entries in the initial 
ACLs. 



Reference 

Organick, E.I., The Mul ti cs System : An Exam i nation of i ts 

Structure . Chapter k, Access Control and Protection, M.l.T. 
Press, Cambridge, Mass. 1972 
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MULTI -SEGMENT FILES 

Segments on Multics have a size limit which is suitable for 
a large class of applications. However/ subsystems which make 
use of large data bases need ways of treating many segments as a 
single file. The approach that has been adopted in Multics is to 
put these segments into a directory and to set the directory's 
mul t i -segment file indicator (formerly called the bit count) to 
some nonzero value. Such a directory is called a mul t i -segment 
file (MSF). 

The convention for MSFs is considered to be at a higher 
level than the file system and command system. That is, the file 
system and most of the command system do not recognize MSFs. To 
manipulate an MSF, the user must use the tools provided him by 
the subsystem which maintains the MSF. For instance, he cannot 
expect to edit an MSF containing ASCII information using a 
standard Multics editor. For user convenience/ the list/ status, 
and delete commands do recognize MSFs. In addition/ the dprint 
command/ if given an MSF, will assume that the mul t i -segment file 
indicator of the MSF is a count of the number of segments in the 
MSF and that if the MSF contains n+1 segments/ then their names 
are the characters 0/ 1, 2, . n. The MSFs produced by the 
file_ I/O System Interface Module (I0SIM) (see the MPM Command 
Section) are in this format, thus making it possible to dprint 
them. 
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BACKUP AND RETR1 EVAL ££ USER STORAGE 

The Multics backup system provides Insurance against the 
involuntary destruction of information maintained by the storage 
system. This insurance is obtained by preserving on magnetic 
tape recent copies of all nonexpendable segments known to the 
storage system, and reclaiming these copies when needed. In 
effect, the backup system augments the reliability of the on-line 
storage system. 

It is the primary responsibility of the backup system to 
protect users against damage to their segments that can result 
from a system failure or error. As a secondary duty, the backup 
system also protects users against self-inflicted damage to their 
segments. 

The backup system performs the following four functions: 

1) segment backup copying 

the copying of segments from the Multics directory hierarchy 
onto tape. 

2) retrieving 

the recovering (during normal Multics operation) of segments 
that have been copied onto tape. 

3) reloading 

the recovering of the entire contents of on-line storage 
(generally following a system crash) in order to resume 
Multics operation. 

k) salvaging 

the finding, reporting, and correcting of errors contained in 
the Multics directory hierarchy. 

Users are normally concerned only with segment backup copying and 
retrieving, since reloading and salvaging are system functions 
performed automatically when the need arises. 

A number of installation-determined parameters occur in the 
Multics backup system; in particular, the frequency of segment 
backup copying and the length of time for which tapes are kept 
are determined locally. Examples in the text are typical values 
and should not be relied on. The user should check with his 
local installation to find out these local values. 
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Segment Backup Copvi ng 

The segment backup copying mechanism searches out, selects, 
and copies onto tape, segments from the Multics directory 
hierarchy. (The term "dumping" has been used to indicate backup 
copying for historical reasons. It is a piece of jargon local to 
Multics andJs avoided in this write-up as much as possible.) At 
the same time it produces a map indicating the segments included 
in each backup copy. The copying mechanism operates in three 
different modes corresponding to three different types of backup 
copies — incremental/ consolidated, and complete. These backup 
copies are distinguished by three different criteria used to 
select candidates for copying (as described below). 

During each of the three types of backup copying, those 
portions of the hierarchy specified by a control segment are 
searched. In current practice, only two subdirectories of the 
root di rectory are not searched. One of these, 
>system_l i brary_l (which is logically a subset of 
>system_l i brary_standard) , is always reloaded from a Multics 
system tape and therefore does not require the services of 
backup. In >sy stem_l i brary_l is contained the hardcore system 
plus that part of the command system needed during reloading. 
The other subdirectory, >process_di r_d i r, contains only 
per-process information which is temporary in nature and hence 
also does not require the services of backup. All other sections 
of the hierarchy are included in the backup copying search path. 
See the MPM Reference Guide section, The Storage System 
Directory Hierarchy. 

Two system processes are employed by the backup system for 
the purpose of segment backup copying, namely Backup. SysDaemon 
and Dumper . SysDaemon. The Backup process is used to produce 
incremental and consolidated backup copies, whereas the Dumper 
process is used to produce complete backup copies. Hence, 
complete backup copies can be produced concurrently with either 
incremental or consolidated backup copies. 

Incremental Backup Coovi ng 

Incremental backup copying is the principal technique used 
to keep the backup system abreast of changes to on-line storage. 

It is the purpose of an incremental backup copier to discover 
modifications to on-line information not reflected in backup tape 
storage. The incremental backup copier locates and copies all 
segments in its search path that have been modified more recently 
than they have been copied. This criterion is easily determined 
by comparing the date/time modified (maintained by the storage 
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system) and the date/time dumped (maintained by the backup 
system) found in the entry for any given segment. Immediately 
after backup copying a segment/ the incremental backup copier 
resets the date/time dumped for that segment. The net effect of 
the incremental backup copying scheme is to limit the amount of 
information that can be lost to those modifications that have 
occurred since the last backup copy. 

Incremental backup copying is triggered periodically by a 
system v,t imi ng mechanism. In order to restrict the maximum time 
span during which modifications to on-line storage can go 
unnoticed by the backup system, it follows that incremental 
backup copies should be produced frequently. On the other hand, 
because the backup daemon competes with ordinary users and exerts 
a considerable drain on system resources/ it becomes economically 
desirable to lower the frequency of incremental backup copies. 
Therefore/ the incremental backup copying rate at an installation 
is chosen as a compromise between these two considerations. A 
triggering interval of one hour might be chosen. This does not 
imply/ however, that an incremental backup copy will necessarily 
finish within a single one-hour time interval. In fact/ since 
the incremental backup copier normally enjoys no scheduling 
advantage/ an incremental backup copy typically might require 
several one-hour intervals to complete during hours of heavy 
system load. A new backup copy begins immediately following the 
completion of such an overtime backup copy. 

The backup system does not guarantee that segments are 
copied in a consistent state. In other words, it is possible 
that while the backup copier is copying a segment/ another 
process might be writing into that same segment. Thus, an 
inconsistent copy of a segment might be produced. Note, however/ 
that modifications that cause a segment copy to be inconsistent 
also cause another copy of the segment to be produced on the next 
pass of the incremental backup copier. Therefore/ a consistent 
copy is eventually produced. 

Consol i dated Backup Copy i ng 

A consolidated backup copier locates and copies segments in 
its search path that have been modified after some specified time 
in the past. For example, an installation might choose to run a 
consolidated backup copier every midnight to copy all segments 
modified since the preceding midnight; i.e., since the preceding 
consolidated backup copy. When used in this manner, the 
consolidated backup copier is essentially imitating an 
incremental backup copier except, of course, that the interval 
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between consolidated copies is longer. Another possible practice 
is to backup copy all segments modified since the last complete 
backup copy (see below). 

The original motivation behind consolidated backup copying 
was the need to consolidate the most recent copies of segments 
from a group of incremental tapes in order to reduce the amount 
of time needed to reload these tapes. An inefficient solution to 
this problem would be to actually merge a group of incremental 
tapes. Instead, the consolidated backup copy was invented to 
achieve the same goal. Notice that since a consolidated backup 
copier catches modifications that have accrued over a period of 
time encompassing many incremental backup copies, it effectively 
consolidates the most recent information from a group of 
incremental tapes. Furthermore, the consolidated backup copier 
also picks up segments that have been modified more recently 
than the last incremental backup copy. Hence, a consolidated 
backup copier performs the work of an incremental backup copier 
as wel 1 . 

A second motive for consolidated backup copying might be 
simply expressed as "two copies are better than one". There is 
some question, however, as to when secondary copies should be 
produced. An alternate and somewhat more obvious strategy, for 
example, would be to have the incremental backup copier produce 
duplicate tapes. This method would guarantee that both primary 
and secondary copies were identical. Such a facility is, in 
fact, implemented in the backup copier, but is not used for 
incremental backup copying. The principal shortcoming of the 
duplicate tape strategy is that the primary and secondary copies 
are not produced in a sufficiently independent fashion. 
Therefore, both copies are, to a certain extent, susceptible to 
the same errors. This is particularly true of operational errors 
and, to a lesser degree, is true of hardware and software errors. 
Also, the duplicate tape strategy is comparatively expensive and 
vol umi nous. 

Compl ete Backup Copy i ng 

A complete backup copier simply backup copies every segment 
in its search path without regard for modification time. Unlike 

modification-driven backup copying which attempts to keep the 
backup system up-to-date, complete backup copying is somewhat 
different in purpose and follows a more leisurely schedule. 
During a complete backup copy, the date/time dumped is not reset. 
Therefore, complete backup copying does not interact in any way 
with incremental or consolidated backup copying. 
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A complete backup copy establishes a checkpoint in time, 
essentially a snapshot of the entire Multics storage hierarchy. 
!f it should ever become necessary to recover from scratch the 
contents of on-line storage/ then the most recent complete backup 
copy marks a cutoff point beyond which no older backup tapes need 
be inspected. 

Another purpose of complete backup copying involves the tape 
retention strategy. The high production rate of incremental and 
consolidated tapes makes the retention of these tapes for long 
periods of time impractical. Therefore, incremental and 
consolidated tapes are kept for some short time, perhaps three 
weeks. Complete backup copy tapes are retained for a longer 
time, perhaps six months, with the exception of one complete 
backup copy per month that might be held for a period of one 
year. 

Retr i evi ng 

The segment retrieval mechanism used by the backup system 
consists of a group of programs known as the reloader/retr i ever . 
The reloader/retr i ever is used to recover segments from tapes 
produced by the backup copier. Retrieving, which occurs during 
normal Multics operation, is distinguished from reloading, which 
occurs prior to normal Multics operation. 

When a user notices that a segment or directory has been 
lost or damaged, he can submit a request to the Multics 
operations staff for that segment or directory to be retrieved 
from a backup tape. The problem he faces, of course, is 
determining which backup copying operation produced the copy he 
wishes to retrieve. Usually the most recently produced copy is 
wanted. In the case of a damaged segment, however, the damaged 
version is likely to have been backup copied as well, and hence 
the most recent copy is not wanted. Hopefully a user knows 
approximately when his segment was lost or damaged. Also, he 
should remember if the segment has been recently modified. Using 
these two pieces of information he can make a reasonable guess as 
to which backup copy contains a suitable copy of a given segment. 

Once a conjecture has been made as to which backup copy 
contains the desired copy, the conjecture can be verified by 
examining the corresponding backup copy map. The map indicates 
the tape reel on which the backup copy was written. A feature of 
the backup copy map which is sometimes helpful is the date/time 
last dumped for the segment, which effectively points to the next 
most recent backup copy of the segment. 
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The user can specify that a single segment, a directory 
without its subtree/ or a directory including its subtree be 
retrieved. A directory for which the subtree is not retrieved 
contains only the links and access control information associated 
with the directory itself. 

A user can also specify that the segment or directory be 
retrieved by a different path name. A single segment or a 
directory without a subtree can be relocated at any point in the 
storage system hierarchy. A directory subtree can be relocated 
at any point at the same level in the hierarchy (i.e., the number 
of > characters in the path name of the directory cannot change). 

Normally the most recent copy of an entry on the specified 
tape is retrieved. However/ the user can specify that the first 
occurrence is to be retrieved instead/ presumably to retrieve a 
particular i ntermed iate -copy. 
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USE OF THE INPUT AND OUTPUT FACILITIES 

Multics provides various means for performing input and 
output, i.e., moving data in to or out of the Multics system. 
Users should note that input/output (I/O) in Multics is not the 
means by which the data stored in segments in the Multics storage 
system is referenced. Data in the Multics storage system is 
internal to Multics and referencing such data, therefore, does 
not require moving it in to or out of the system. Refer to the 
MPM Reference Guide Section on Using the Multics Storage System 
for information on referencing segments. Most I/O involves one 
of the many available peripheral devices such as typewriters, 
printers, tape drives, card readers and punches, graphic devices, 
etc. All I/O operations in Multics make use of the I/O system. 
The use of the Multics I/O system is described in the MPM 
Reference Guide Section on the Use of the Input and Output 
System. The I/O system provides a general means by wh i ch any I/O 
capable of being performed in Multics can be accomplished. 
However, for most common uses of I/O, procedures are provided 
which eliminate the need for the user to have a working knowledge 
of the I/O system. This section provides a brief introduction to 
some of these facilities and indicates where further information 
about each facility can be found. The MPM Reference Guide 
Section, Available Input and Output Facilities, provides a 
complete list of I/O facilities. 

Translators 

Multics provides several higher level languages which have 
built-in I/O facilities such as formatting and directing I/O to 
and from various devices (e.g., PL/I, FORTRAN). Users should 
consult the appropriate language manuals for a description of 
these fac i 1 i t ies . 

Console Input/Output 

For simple reading from and writing to the user f s console, 
the entries ios_$ read_.pt r and i os_$wr i te_ptr are provided. See 
the MPM write-up on ios__. 

Formatting 

Two subroutines, ioa_ and write_list_, are provided for 
formatting output before it is printed on the console. The 
subroutine read__list__ is used to parse input read from the 
console. See the MPM Subroutine Calls Section describing these 
programs . 
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Redi recting Consol e Output to a Segment 

The file_output command will cause all subsequent output 
normally printed on the user's console to be written instead to a 
segment in the file system. The consol e__output command causes 
such output to be directed again to the console. See the MPM 
Command Section describing these commands. 

Printing of Segment Contents 

The contents of segments that contain exclusively Multics 
ASCII characters may be printed on the console by invoking the 
"print" command. The contents of a segment which does not 
contain characters can be printed in octal using the command 
dump_segment or the Multics debugger/ debug. See the MPM Command 
Section describing these commands. 

Bui k I nput/OutPUt 

In order to permit all users to make use of certain critical 
peripheral I/O devices in an efficient manner, Multics provides a 
service in which users may queue requests to input or output data 
using these devices. These devices are: 

1) Printer - The contents of a segment containing Multics ASCII 
characters can be printed on a high speed printer using the 
dprint command. The dprint command queues the request for 
printing and, at some later time, the contents of the segment 
will be printed and made available to the user by the Multics 
installation. The printed output will consist of one or more 
pages of header indicating the path name of the segment and 
the user issuing the request, the contents of the segment, and 
one or more pages of information detailing the charges 
incurred in printing the contents of the segment. See the MPM 
command dprint. 

2) Card Punch - The contents of a segment may be punched on cards 
using the dpunch command. In a manner similar to printing, 
the dpunch command queues the requests for punching and, at 
some later time, the contents of the segment will be punched 
and made available to the requester. The output deck will 
consist of several "flip" cards identifying the segment and 
requester, the contents of the segment in one of several 
possible formats, and cards indicating the end of a deck. For 
a description of the various types of card format, see the MPM 
Reference Guide Section on Bulk Input and Output. The use of 
the dpunch command is described in the MPM Command Section. 



Copyright, 1971, Massachusetts Institute of Technology 
All rights reserved. 




MULT ICS PROGRAMMERS' MANUAL 



Use of I /0 Fac i 1 i t i es 
I /0 Fac i 1 i t i es 
Page 3 
10/21/71 



3) Card Reader - Information contained in a deck of cards may be 
read into the Multics system by submitting the deck to the 



which contains information about the deck and how it is to be 
located within the system, the cards containing the data in 
one of the Multics standard formats, and a special card 
indicating the end of the deck. The contents of the deck 
will be input at some later time to a segment in a special 
directory in the Multics system and a link to this segment 
placed as indicated on the control card. After the deck is 
read in, it will be made available to the submitter. The 
exact format of input decks is described in the MPM Reference 
Guide Section on Bulk Input and Output. 



Users having I/O devices with graphic I/O capabilities can 
make use of the Multics graphic system. The graphic system uses 
a general intermediate graphic structure language that permits 
programs to be written in a dev i ce- i ndependent manner. For 
simple graphic applications/ see the MPM subroutine plot_. Users 
wishing more sophisticated graphic capabilities should see the 
MPM Reference Guide Section on Graphics Support on Multics and 
obtain the MPM Graphics Users 1 Supplement. 
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USE 0£ TJHE INPUT AND OUTPUT SYSTEM 

The primary purpose of the I/O system is to allow a process 
to communicate with external physical devices such as 
typewriters/ on-line printers/ tape drives, etc. In other words, 
I/O is the movement of data to and from the system, as opposed to 
the management of data within the system. An example of the 
latter is the storage system. On the Multics hardware, I/O 
communications are handled by the I/O channel controller which is 
fed instructions by the CPU. It is the function of the I/O 
system to translate high level I/O system calls into channel 
controller instructions. This is accomplished through various 
levels of programming both within and outside the hardcore 
supervisor. The final result of this programming is that the 
user is provided with a very flexible set of subroutines which 
allow him to easily communicate with devices. The flexibility is 
provided by the use of I/O stream names for addressing devices, 
the Attach Table for associating the stream name with a device, 
and a means by which the association can be changed. The user is 
able to perform I/O operations upon diverse devices by using a 
single set of simple operations. This is possible because the 
system is designed so that all I/O devices appear functionally 
identical at the user procedure level. Exceptions to the 
functional equivalence occur in devices upon which certain 
operations cannot be performed; for example, reading from a 
printer or writing to a card reader. The combination of stream 
names and functional equivalence of devices from the user level 
allows run-time specification and modification of the device or 
devices to which I/O is directed without modification of 
programs . 

interface Modules 

The procedure responsible for coordinating the communication 
with a particular device is called an interface module. Each 
device has at least one associated interface module. The 
interface module is responsible for lending the appearance of 
functional equivalence of a device to the I/O system. It 
contains entry points whose calling sequences and functions are 
defined by system wide convention. These common operations are 
transformed by the interface module into calls to other I/O 
system subroutines in order to perform the actual I/O. It is the 
primary purpose of the interface module to create the common 
appearance of the device to higher levels of the I/O system in 
order that I/O calls directed to different devices can be made in 
a standard manner. 
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There are basically three types of interface modules: 

1) Device Interface Module (DIM): This type of module 
coordinates communications with a particular external 
physical device such as a typewriter, printer, or tape 
dr i ve . 

2) Pseudo-Device Interface Module: This type of module permits 
a process to communicate with something other than a 
physical device as if it were a device. The best example is 
the Storage System Interface Module (SSIM) which allows a 
process to use a segment (or set of segments) in the storage 
system as an I/O device. Another use could be to create a 
pseudo-device to simulate an actual device for testing 
purposes. 

3) Intermediate Interface Module: This type of module is 
intended to serve as an intermediary between a user program 
and another interface module and will be discussed in more 
detail later. It serves to modify an I/O communication 
before the DIM or pseudo-DIM is called. The modification 
might be the formatting of data or redirecting of the call 
to a different device or set of devices. 

In order to perform its function, the interface module may 
call upon other routines for such things as code conversion or 
buffering. In some cases, device dependent code is placed in the 
Hardcore Ring supervisor for efficiency (e.g., the major portion 
of the typewriter DIM is in The Hardcore Ring). If an external 
device is involved, the interface module will have to send 
instructions to the hardware channel controller. A procedure in 
the supervisor has been provided for this purpose. The channel 
controller interface module is responsible for giving 
instructions (Data Control Words (DCW)) to the channel controller 
and is callable by User Ring procedures. 

streams and xh& U& $wi ten 

The user of the I/O system does not directly call an 
interface module. I/O calls are made by specifying a symbolic 
stream name. One of the arguments of each call to the I/O system 
is a stream name. Each stream name is associated with an 
interface module and a particular device. Thus, when a user 
wishes to obtain his input from or direct his output to a 
different device, he does not have to rewrite his programs; he 
simply changes the device with which the specified stream is 
associated, assuming the device is capable of the desired 
operat ions . 
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The association of stream names and interface modules and 
devices is kept in a data base called the Attach Table. The 
procedure which maintains and uses the Attach Table is called the 
I/O switch. All user calls to the I/O system are actually calls 
to the I/O switch. The switch finds the specified stream name in 
the Attach Table and calls the associated interface module at the 
appropriate entry. Two calls to the I/O switch" are handled in a 
special manner. The attach call is used to initialize a stream 
and a device for communication. It also causes the I/O switch to 
create an association in the Attach Table between the specified 
stream name, interface module/ and a particular device. The 
creation of such an association is initiated by use of the 
fol lowi ng cal 1 . 

call attach ("user.i/o", "typewr i ter", "ttylOQ"); 

This call causes the I/O switch to call the typewriter interface 
module/ which has been specified by its name "typewriter" to 
prepare the specified typewriter, "ttylOO"/ for communications. 
If this is successful/ the I/O switch creates an entry in the 
Attach Table relating the stream name "user_i/o" to "ttylOO" with 
the typewriter interface module being specified as the control 
program. All further I/O calls on the stream "user_i/o" will be 
forwarded to the typewriter interface module to be performed on 
"ttylOO". The detach call serves the opposite purpose. It 
causes the I/O switch to terminate communication with the device 
and remove the association from the Attach Table. 

Intermediate Interface Modules 

The attachments discussed so far associate a stream name 
with an interface module and a device. Another type of 
attachment associates a stream name with an interface module and 
another stream name. The interface modules involved in such 
attachments serve to intercept the I/O call made on the first 
stream and/ after performing some processing/ make another call 
to the I/O switch on the second stream. Such interface modules 
are effectively spliced into the logical flow of control and are, 
therefore, called intermediate interface modules. Such interface 
modules may be used for formatting data before it is actually 
passed on to a device. There are also some other important uses 
of intermediate interface modules. 

The syn intermediate interface module simply passes an I/O 
call to a different stream. If the stream "user_output" is 
attached via the syn interface module to the stream "user_i/o", 
then all I/O calls to "user_output" will be directed by the syn 
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interface module to the stream "user_J /o". A call to either 
stream will have the same result and the streams are, therefore, 
synonymous. syn attachments are useful because they are much 
easier to change than device attachments because no device 
initializations or terminations are necessary. (Initialization 
and termination are those operations a DIM must perform to start 
or end communication with a physical device.) 

The broadcast interface module is used for attaching a 
stream to many other streams. In doing so, a call on the first 
stream will result in calls on all the streams to which it is 
attached. This is a means by which I/O calls may fan out. 

Figure 1 gives a block diagram of the I/O system showing the 
various types of modules which can exist. 

Modes and Data Organization 

Each attachment has associated with it certain attributes 

called modes. The precise interpretation of a mode is dependent 

upon the interface module being invoked, but some general 
statements about modes can be made. 

The read and write modes specify that the read (input) and 
write (output) operations can be performed on this device. The 
user may wish to use a teletype only for writing and, therefore, 
may not wish to give it the read attribute. On devices such as a 
printer, the read attribute is meaningless; therefore, attempts 
to read from a printer will cause an error status to be reflected 
back to the user. 



1/0 data consists of a collection of elements where an 
element is the smallest indivisible unit of information. The 
type of an element is determined by its size, i.e., the number of 
bits it contains. Data operated on by a single 1/0 call to an 
interface module must consist of elements of the same type 
(size). Entries are provided to change the element size accepted 
by an interface module. An element could be a character or a bit 
or a word or a fixed-size logical record. The data element size 
is usually a function of the type of information being 
transferred and is not necessarily a function of the device. In 
all calls to the I/O system involving the reading or writing of 
data, the amount of data to be transferred is expressed as an 
integral number of elements. 

There are two basic categories for data: physical and 
logical. The physical representation is the way the actual 
device accepts the data. The organization of logical data is 
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defined by the program. For example, magnetic tape requires that 
data be organized into physical records with gaps between the 
records. However, the user receives a linear stream of data as 
the logical representation. 

Other modes are concerned with the synchronization of I/O 
calls and the actual I/O operations. The use of such features as 
read-ahead and write-behind means that the I/O operation may not 
be performed at the time of the actual I/O call. Various modes 
and calls are provided to give the user some control over the 
synchronization. 

Status Report i ne 

It is necessary for the I/O system caller to know the status 
of his I/O call. This is especially true since the I/O operation 
may not be performed at the same time as the call. For this 
reason, a status argument is provided in each call. The I/O 
system returns essentially three pieces of information in the 
status argument. A code describing the nature of an error, if 
one occurs, is returned. Some bits are returned indicating the 
state of the transaction. The status argument also includes a 
unique identifier which enables the I/O system to identify the 
transaction if the caller wishes to request information about or 
modify the transaction at a later time. Status is described in 
more detail later in this document. 

Usage 

The various calls to the I/O system are described in the MPM 
write-up on ios_. In order to illustrate some of the uses to 
which the I/O system can be put, a few examples of its use 
follow. For ease of explanation, the calls shown in this section 
may not correspond exactly to the calls available on Multics; the 
reader should refer to other MPM sections for exact calling 
sequences . 

A typical user performs I/O communications with a single 
device, a typewriter. To initialize this communication, calls 
are made to the I/O system at process initialization time. The 
following three calls are made: 

call attach ( "user_i /o", "typewriter", "ttylOO", 
"read, write", status); 

call attach ( "user_output", "syn", "user_i/o", "write", 
status ) ; 
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call attach ( n user_i nput", "syn M , "user.i/o", "read", 
status) ; 

The first call establishes that the device whose identifier is 
"ttylOO" will be controlled by the I/O interface module named 
"typewriter" for reading and writing. All subsequent operations 
for this device will be made by referencing the stream name 
"user_i/o". Information about the status of this I/O call is 
returned in "status". The second call establishes a synonym for 
"user_i/o" called "user_output". The "write" as the fourth 
argument, however, restricts this synonym to write calls only. 
Any write call to the stream "user__output" is now synonymous to a 
write call on the stream "user_i/o". Any read call on 
"user__output" will be an error that will be reflected in the 
status string of the read call. The third attach call 
establishes another synonym for "user__i/o" for reading only and 
is called "user_i nput". 

The process may now communicate with the typewriter 
"ttylOO". To type something out on the typewriter, the process 
i ssues a wr i te cal 1 : 

call write ("user__output", workspace, nelements, status); 

This call writes the specified number of elements (nelements) of 
data contained in workspace onto the stream "user__output" . This 
results in a call to the stream "user_J/o". The typewriter 
interface module is invoked to transmit the information to 
"ttylOO". The sequence of calls is illustrated in Figure 2. 

The process may also wish to receive input typed by the user 
on the typewriter. For this purpose, the following call is 
i ssued: 

call read ( "user_j nput", workspace, nelements, nactual, 
status) ; 

This call reads into workspace the specified number of elements 
(nelements) from "ttylOO" following a similar sequence of calls 
as in the write request. Read calls have an additional feature 
in that they make use of read delimiters. The typewriter DIM 
will attempt to read the specified number of elements; however, 
if, in doing so, it encounters a read delimiter, reading ceases 
at that point. The actual number of characters read is returned 
as nactual. For example, if the process issued the call: 

call read ( "user_i nput", workspace, 10, nactual, status); 
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and the string typed on "ttylOO" by the user is abcdef gh i j kl mn 
and the read delimiter is d, then the string abed will be placed 
in workspace and nactual will be set to four. If, however, the 
read delimiter is m, then workspace will be set to contain 
abedefghij and nactual set to ten since only ten elements 
(characters in this case) were requested in the read call. 
Delimiters and element types are established by various calls to 
the I/O system. The most commonly used read delimiter is the 
"new line" character. 

Let us assume that the user wishes to direct his output to a 
segment in the storage system instead of to his typewriter. To 
do this, he may issue the following calls: 

call attach ( "segmen t_st ream", "file__", "segmen t_name", 
"write", status); 

call detach ( "user_output", "user__i /o", status); 

call attach ("user_output", "syn", "segment_s tream", 
"write"/ status); 

The first call initializes a segment whose name is "segmen t_name" 
as an I/O device via the SSIM. All write calls on the stream 
"segment_s tream" will be directed to the segment "segmen t_name" . 
However/ we assume that the programs the user is about to invoke 
use the stream "user_output" for writing since this is the stream 
that normally is used for output. The detach call and the 
subsequent attach call serve to modify the synonymi zat i on of 
"user__putput" . "user__output" is now synonymous to 

"segment_stream" for writing and all write requests will now be 
directed to the SSIM for writing into the segment 
"segmen t__name". Note that if "user_output " had been attached 
directly to the typewriter, instead of indirectly through the syn 
interface module, it would have been necessary to terminate the 
actual device, i.e., ttylOO, to accomplish the detachment. By 
having the extra level of indirection, such changes are simply 
table modifications by the syn interface module. Now all output 
v/ritten to the stream "user_output" will appear in "segment_name" 
instead of on the typewriter. In order to revert back to the 
typewriter, the process issues the calls: 

call detach ( "user_output", "segment_s tream", status); 

call attach ( "user__output", "syn", "user_i/o", "write", 
status ) ; 
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Note that the segment remains attached via the stream 
"segment_stream" to allow the user to switch back to segment 
output more easily. When the user is sure he will no longer use 
the segment for output, he issues the call: 

call detach ("segment_stream ,, / "segment^name", status); 

Note/ also, that during this entire operation, the user's input 
stream was never affected, i.e., read calls directed to the 
stream "user_i nput" will obtain data from the typewriter. 

Certain Multics commands and the Multics user environment 
expect the standard streams user__output, user_input, and 
er ror_output to be attached to other streams via the syn 
interface module. This assures that if any of these streams are 
detached and subsequently reattached, as is the case when the 
user quits and starts, that no information about the attachment 
is lost. Users should therefore attach these streams using only 
the syn interface module. 

I /0 Terms 

Below are some of the more important terms used in 
describing the I/O system. 

Attachment 

An attachment is the association of one stream name with an 
interface module and either a device ID or another stream name. 
This association is established by an attach call. Subsequent to 
an attachment, data may be read or written by issuing a read or 
write call with the appropriate stream name. 

Del imi ters 

There are two kinds of I/O delimiters meaningful to an I/O 
user on input. These are the break characters and the read 
delimiters which are established by means of the setdelim call. 
A break character is meaningful only to an interactive device and 
serves three functions: it delimits physical interrupts, 
canonical ization, and erase-and-ki 1 1 processing. A break 
character is an interrupt delimiter in that it is recognized by 
the hardware channel controller and causes an immediate 
interrupt. A break character is an erase-and-ki 1 1 delimiter in 
that its presence permits erase-and-ki 1 1 processing to take place 
over all characters received since the preceding break character. 
A break character is a canon i cal i zat i on delimiter in that its 
presence permits canon ical izat ion to take place over all elements 
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received since the preceding canon i cal i zat i on delimiter. For 
certain devices (e.g., typewr i ters ) , the "new line" character is 
the default break character. ! n addition, whether established as 
a break character or not, the "new line" character "always 
delimits canon i ca 1 i zat i on and erase-and-ki 1 1 processing. A read 
delimiter affects the amount of data transferred to the user 
program during a read call. A read call continues to transmit 
data to the caller until a read delimiter is recognized (and 
transferred) or until the specified amount of data has been 
transferred. The current break characters and read delimiters 
may be determined or modified using the getdel im or setdel im 
cal 1 s . 

Element 

An element is a linear array of bits. It is the smallest 

data entity referred to by an I/O call. The most frequent 

element sizes are 1 (bit)/ 9 (character), and 36 (word) bits. 

The current element size of a stream may be determined or 
modified using the getsize or setsize calls. 

Modes 

The modes of an attachment specify the setting of a 
collection of attributes relevant to the intended use of the 
specified stream name. Modes are expressed as a character string 
to the attach call or a changemode call. The string consists of 
key words, specifying individual modes, separated by commas. 
Modes need only be understandable by the interface module 
receiving the attach or changemode call. Some modes, however, 
have commonly accepted meanings: 

1) read data may be input from this stream; 

2) write data may be output to this stream. 

The key words in a mode string may be preceded by the 
circumflex character which indicates the opposite of the mode. 
For example, the mode string "read, ~W i te" indicates data may be 
input from this stream but no outputting may be done to this 
stream. Note that the mode string in the attach and changemode 
calls serves only to change the setting of the modes specified in 
the string and does not affect the setting of modes not specified 
in the string. In the attach call, the modes are changed from 
the default; in the changemode call, the modes are changed from 
the current setting. 
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Reference Pointers 

Associated with each stream are five values called reference 
pointers. A reference pointer is the offset of an element of 
data that is of special interest. The five reference pointers 



and 


the elements 


to 


which they point are: 


1) 


read 


the 


next element to be read; 


2) 


wr i te 


the 


next element to be written; 


3) 


f i rst 


the 


first element of data; 


U) 


1 as t 


the 


last element of data; 


5) 


bound 


the 


element beyond which data cannot be written. 




The seek 


I/O 


call may be used to explicitly modify the 



values of these reference pointers. The read reference pointer 
is modified implicitly when a read or read__ptr I/O call inputs 
some data. The write reference pointer is modified implicitly 
when a write or write_ ptr I/O call outputs some data. The last 
reference pointer is implicitly modified by a write or write_ptr 
I/O call which appends to the end of the data. The values of the 
reference pointers always obey the following relations: 

first <. read <. last +1 <. bound +1 

first <. write < last +1 <. bound +1 

For example, if one wanted to start reading the data of a device 
from the beginning one would issue the following seek call: 

call seek (stream, "read", "first"/ 0, status); 

If one wanted to append to the end of the data one would issue 
the cal 1 : 

call seek (stream, "write", "last", 1, status); 

If one wanted to erase the data one would issue the call: 

call seek (stream, "last", "first", -1, status); 

Note that the values of reference pointers are relative to one 
another. They do not have absolute values. As with I/O calls, 
all of the five reference pointers may not be implemented by each 
I/O System Interface Module (I0SIM). The MPM sections on lOSIMs 
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call requesting the read operation (read-ahead). If a stream is 
write asynchronous/ the write operation may not complete until 
after the write call requesting the write operation has returned 
(write-behind). Synchronization modes may be established using 
the readsync and writesync calls. 

Workspace 

The buffer area in the user's address space/ to or from 
which a request to transfer data is directed/ is referred to as 
the workspace. A read call reads an integral number of elements 
into a specified workspace; a write call writes an integral 
number of elements from the workspace. 
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AVAI LABLE INPUT AND OUTPUT FACI LITI ES 

The following is a list of commands and subroutines 
available to users that are commonly used to provide input and 



output 



rune t i ons . 



organ i zed 



i 

uy 



unct s on 



provided. The procedures listed as Miscellaneous I/O System 
Procedures and those subroutines categorized as Input/Output 
System Interface Modules (IOSIM) require some knowledge of the 
Multics I/O system in order to be used. (See the MPM Reference 
Guide Section on the Use of the Input and Output System.) The 
MPM section under which each module is described is given for 
easy reference. Note that the lOSIMs are categorized under the 
MPM Subroutine Calls Section. 



S impl e I nput/Outout 

ios_$read__ptr 
ios__$wr i te__pt r 

Formatted I nout/OutPut 
ioa__ 

read_l i st_ 
wr i te_1 i st_ 



MPM subroutine 
MPM subroutine 



MPM subroutine 
MPM subroutine 
MPM subroutine 



Input/Output with Segments la Ite File System 
consol e__output 



MPM command 



debug 

dump_segment 
exec_com 
f ile_ 

f i 1 e_output 



MPM 
MPM 
MPM 
MPM 



command 
command 
command 
IOSIM 



(see the MPM 
f i 1 e_output ) 



command 



print 

jransl ators 

fortran 
1 i sp 
Pll 

Pulk Input/Output 

With the high speed printer: 



MPM command 
MPM command 



MPM command (see the FORTRAN Manual) 
MPM command (see the LISP Manual) 
MPM command (see the PL/1 Manual) 



dpr int 



MPM command 
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With punched cards: 

dpunch MPM command 

Card Input 

With magnetic tape: 

tape_ until general tape reel mounting 

nstd_ facilities are available/ these 

lOSIM's may be used only by special 
arrangement with operations. 

See also the MPM Reference Guide Section on Bulk Input and 
Output . 

firaph i cs 

plot_ MPM subroutine 

See also the MPM Reference Guide Section on Graphics Support on 
Multics and the MPM Graphics Users 1 Supplement. 

Input/Output Devices 

Cards : 

dpunch MPM command 

Card Input 

See also the MPM Reference Guide Section on Bulk Input and 
Output . 

Consoles (typewriters/ teletypes/ ARDS/ etc.): 

iomode MPM command 

line_length MPM command 

tw_ MPM I0SIM 

Printer (high speed): 

dprint MPM command 

Mi seel laneous 1/0 System Procedures 

broadcasts MPM I OS I M 

get__at__ent ry_ MPM subroutine 

iocal 1 MPM command 

ios__ MPM subroutine 
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pr int_attach_tabl e MPM command 

syn MPM I0SIM 

See also the MPM Reference Guide Section on the Use of the Input 
and Output System. 
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BULK INPUT AND OUTPUT 

The Multics system currently has provisions for three types 
of bulk I/O: high speed printed output, punched card input, and 
punched card output. 

Printed Output 

The dprint command (see the MPM Command Section) causes the 
contents of a Multics segment containing Multics ASCII characters 
to be printed on a high speed printer. 

The printed output will be of the following form: 

1) One or two header sheets containing the pathname of the 
segment printed, the identification of the requesting 
process, and a character string, if any, supplied by the 
requester in the dprint command. 

2) The contents of the segment. Printed lines contain 136 
character positions. If a line to be printed contains more 
than 136 character positions, it will be continued on the 
fol lowi ng 1 i ne. 

3) A sheet that summarizes the charges incurred in printing the 
contents of the segment. 

Punched Card Input 

Facilities are provided to read punched card decks into 
Multics segments. There are three types of card formats which 
can currently be input to Multics: Multics card codes, 7punch, 
and raw. 

1) Multics card codes are defined in the MPM Reference Guide 
Section on Punched Card Codes. Essentially, they comprise a 
superset of the EBCDIC card punch codes, and are producible 
by 029 key punches. The 12 bit card codes are converted to 
9 bit ASCII codes. (The escape conventions mentioned in the 
Punched Card Codes Section have not yet been implemented.) 

2) 7punch decks are binary representations of existing 
segments, and the data portions of the cards are read in 
exactly as they were punched out. 

3) Raw decks are simply read into Multics segments without any 
conversion, and without regard to format. That is, the 960 
bits on each card are read into the segment, in column 
order. Any desired conversion may then be performed by the 
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user . 



Note that "flip" cards (and other sorts of labelling cards 
from other systems) are not read correctly and should be removed 
from decks. 



Procedure 

Each deck must begin with an 029 key punch produced control 
card in the format described below, and end with a card which has 
a 5-7 multiple punch in column 1. The decks are submitted to 
Operations/ and will, in general, be read in by the next day. 
Owing to protection considerations, segments will be created in a 
system directory rather than placed directly in the user's 
directory; a link to the input segment will be placed in the 
user's directory by the card reading program, through which the 
segment may be copied. In order that the link may be created, 
the user must not have removed append access for * . SysDaemon . * 
for the directory in question. (Note that SysDaemon is 
automatically granted access when directories are created.) 



Note that segments must be copied from the system directory 
v/ithin a reasonable time, as the segments in that directory will 
be periodically deleted. 

Control Card Format 

TYPE DIRECTORY ENTRY ACCESS NAME 



1) TYPE is the deck type. Currently, the valid types are 

MCC (for Mul tics card codes decks), VI I PUNCH (for 
7punched decks), and RAW (for unconverted decks). 

2) DIRECTORY is the pathname of the directory into which a link 

to the input segment will be placed. 

5) ENTRY is the desired entry name of the link to the input 

segment. Note that this entry name must not 
already exist, as the card reading program will 
not attempt to resolve name duplications. 



k) ACCESS_NAME is the access control name which is to be given 
read access to the Tnput segment. See the MPM 
Reference Guide Section on Naming Conventions for 
a description of access control names. 

The items are to be separated by one or more blanks; all four 
items must be specified. 
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The format is shown in upper case because the 029 key punch 
prints that way. However/ pathnames and access control names may 
contain both upper and lower case. Therefore, the card reading 
program will map all letters on the control card to lower case 
except those letters immediately following an escape character 
(£). For example, *.£MULTICS.* as an access name would be 
interpreted as *.Multics.*. This convention is established as an 
interim measure for ease in punching control cards, and will be 
superseded when the escapes of the Punched Card Codes Reference 
Guide Section have been implemented. 

Examol e 

Suppose user Doe, working on project Proj , wishes to read a 
FORTRAN source deck into a segment called al pha . fort ran : 

1) The control card, placed in front of the deck, is as 
fol 1 ows : 

MCC >UDD>£PROJHDOE>SUB XALPHA £D0E . £ PROJ . * 

where MCC specifies Multics card code conversion, and XALPHA 
is chosen so that the eventual copy through the link need 
not be renamed. 

2) The control card, deck, and end of file card (5-7 multiple 
punch in column 1) are submitted to Operations. 

3) When the cards have been read, issue a copy command on the 
console for xalpha into al pha . fort ran . If the cards were 
read in successfully, the copy will succeed. If not, xalpha 
will not be found; in this case, check with Operations to 
determine what went wrong. 

Notes on Deck S i ze 

Decks must not exceed the maximum length of a Multics 
segment. A good rule of thumb is to limit decks to single boxes 
of cards, although more precise counts can be made. For "raw" 
reading, the actual maximum is 2,456 cards. For Multics card 
codes, the actual maximum depends on the number of characters 
actually read, as trailing blanks on cards are ignored. Assuming 
all 80 columns are punched on each card, the maximum would be 
3,276 cards. For 7punched decks, the length of the created 
segment depends on the length of the original segment. The 
typical 7punch card represents 22 words, but it may represent as 
many as 4,096 words if the original segment contained that many 
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consecutive words of identical contents. 
Errors 



The operator will return a note with the deck if any errors 
took place during the read. In general, the error should be 
corrected and the deck resubmitted. However, in certain cases it 
is possible to avoid rereading; when the only problem involves 
the input segment bit count or a name duplication in the user's 
directory, the uniquely named segment (in >daemon_di r_di r>cards) 
nay be linked to directly. 

Hul tics Card Output 

The dpunch command (see the MPM Command Section) causes the 
contents of Multics segments to be punched. The segments may be 
punched under mcc, raw, or 7punch conversion modes. 



The 7punch conversion mode essentially furnishes a binary 
representation of a segment, suitable for subsequent reloading. 
The 7punch format also provides sequencing and checksumming; 
nence, it is more secure than the raw mode, provided that the 
segment is being punched in order to serve as additional backup 



and not 


for 


use on any 


system 


other 


than 


Mul tics. 




The 


Mul t i cs 


7punch 


format 


i s as 


fol lows : 












Col umns 








Rows 


1 


2 


3 


it 


5 


6 


7 - 


72 


1-3 


1 

17 
i 


w 


s 


c 


c 


c 


d 


d 


4-6 


I w 


w 


. s 


c 


c 


c 


d . . . 


d 


7-9 


1 

|w 


t 


s 


c 


c 


c 


d 


d 


10-12 


1 

15 


s 


s 


c 


c 


c 


d . • . 


d 



1) 7 and 5 (octal) are 7punch format identifying codes. 



2) wwww is the number of data words on the card, if 

less than 27(3); if greater, it is a 

replication count and indicates how many 

times the single data word on the card is to 
be replicated on reading back in. 
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3) t 



h ) s s s s s 

5) cccccccccccc 

6) dddd ... dddd 



is a last card code. It will be 0 on each 
card of the deck except the last card / where 
it will be 3. The bit count of the segment 
is punched as the last card for Multics 
decks. 

is the sequence number of the card in the 
deck, starting from 0. 

is the full word logical checksum of all bits 
on the card except the checksum itself. 

are the data words. On the last card, 
columns 7-9 contain the bit count (fixed 
binary(35)) and columns 10-80 are 0. Note 
that the word count is 0 on the last/bit 
count card. 



Deck Structure 



Labelling information is punched on "flip" cards, 
structure of Multics produced decks is as follows: 



The 



Card 1: 
Card 2: 

Card 3: 

Card k: 

Cards 5-n.: 
Card n+1: 
Card ri+2: 



A "flip" card containing two rows of X f s 

A "flip" card containing the heading (may be 
more than one card) 

A "flip" card containing the date and time 
punched 

A "flip" card containing the pathname of the 
segment punched (may be more than one card) 

The punched segment 

A "flip" card saying END OF DECK 

A "flip" card containing two rows of X ! s 
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GRAPHICS SUPPORT ON MULTICS 

The basic purpose behind the development of the Multics 
Graphic System is to provide a termi nal - i ndependent general 
purpose graphic interface suitable for use by all graphic 
applications on Multics. A graphic program written at one type 
of graphic terminal should be operable at another type of 
terminal of similar capabilities without modification. A wide 
variety of graphic applications should be supported. The user 
should be able to write his program easily and naturally, and it 
should run in an efficient manner. 

This first attempt at a graphic system for Multics naturally 
represents compromises with the above goals. The Multics Graphic 
System will change as better solutions to the problems involved 
are discovered. These changes will be upward compatible whenever 
possible, and every attempt will be made to support graphic 
programs written for previous versions of the graphic system. 

The idea of terminal independence was adopted from the 
Multics typewriter I/O system, for the same reason that it is so 
important there. A wide variety of console types are connected 
to Multics (including graphic terminals used as video 
typewriters), and this console mix changes with time. To require 
a program to incorporate specific terminal dependencies would 
have severe disadvantages. 

a) User Fragmentation. Only a limited amount of user 
program sharing could take place because a program 
written by a user could not be used by others working at 
different terminals. This kind of fragmentation would 
severely inhibit the development of on-line user 
commun i t i es . 

b) Terminal Immobility. Being able to use only a fraction 
of the terminals connected to the utility is a 
considerable inconvenience. Even worse, the dependence 
of a subsystem on a specific terminal would grossly 
inhibit the transference to new and better types of 
termi nal s . 

c) Certain modules provided by the utility would require a 
different version for each supported terminal type. 

The net result would be to support only a limited number of 
different types of terminals, to inhibit the introduction of new 
types, and to retain an obsolete type long after the desirability 
of its removal had become apparent. 
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While these arguments for terminal independence now apply 
most strongly to typewriters/ as more types of graphic terminals 
are added to Multics, they gain validity for graphics as well. 

What is meant by terminal independence in graphics? There 
are many different types of graphic terminals ranging from 
storage tube terminals to refresh displays with internal 
processing capability. Even a plotter could be connected, though 
not as an interactive console. Each device has its own set of 
special features, such as dotted line or blinking capability. To 
create true device indifference by allowing the use only of those 
features common to all terminals is clearly an intolerable 
solution. Rather, as a compromise solution, an interface 
incorporating the union of all features of existing terminals is 
provided. This interface is extensible to include new features 
of terminals to be attached in the future. 

A user tailors his program to use the features of the 
terminal types he intends to use. When the program is run, the 
use of any unavailable feature is mapped into the most reasonable 
compromise feature of the terminal being operated. Thus, the 
user has a reasonable guarantee that a program coded in accord 
with the limitations of the system's terminal independence 
capability will generate a recognizable picture on practically 
any type of graphic terminal attached to Multics. However, it 
will not necessarily operate equally wel 1 at any terminal. For 
example, a program written to use the dynamic rotation and 
editing capabilities of a programmable display such as an IMLAC 
would operate rather poorly on a storage tube display terminal 
such as the ARDS. 

The motivation to provide a general purpose graphic system 
is to avoid creating and maintaining a multiplicity of systems, 
each oriented towards a separate application. The extra overhead 
borne by the utility is obvious, but also important is the added 
burden of graphic users having to master the idiosyncrasies of 
entirely separate systems. 

The design problem of any general purpose system is that 
generality is often opposite to ease and efficiency of use. A 
system intended to accept a wide variety of tasks may perform few 
of them well. The Multics Graphic System avoids this dilemma in 
a compromise fashion. It provides a sophisticated, 
picture-structure oriented programming interface which is 
suitable for direct use by a knowledgeable programmer. However, 
those desiring a more application oriented or simpler interface 
may use instead application modules that sit between a user 
program and the general graphic interface. The programming 
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interfaces of these application modules present a view of the 
graphic system more structured towards the user's needs. 
Currently, both a casual user module and a plotting module exist. 

Conceptually, the Multics Graphic System can be viewed as a 
double-ended funnel implementing a switching function between a 
particular application interface and a particular terminal type. 




A Conceptual View of the Organization 
of the Multics Graphic System 



(c) Copyright, 1971, Massachusetts Institute of Technology 
All rights reserved. 




MULT ICS PROGRAMMERS 1 MANUAL 



Graph i cs 

I /O Fac il i t ies 

Page h 



The central portion is the core graphic system, through which 
everything is channeled. At the user end, the funnel expands to 
include a number of different application interface modules. The 
user is to select the most appropriate of these for use by his 
graphic program. At the system end, the funnel expands to 
include interface modules for all the different graphic terminals 
attached to the utility. The user exchanges graphic 
communications with his terminal through one of these. 

More extensive graphic system information and graphic system 
module write-ups are available in the MPM Graphics Users' 
Suppl ement . 
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WRITING AN I/O SYSTEM INTERFACE MODULE 

An I/O System Interface Module ( I OS I M) is responsible for 
coordinating all the activities of a particular device or 
pseudo-device. The interface module must functionally provide 
some or all of the services called for in the general 
specifications of the I/O system. These services are described 
in the MPM section for the subrout i ne ios_. In order that the 
I/O switch be able to call interface modules, these modules must 
have fixed calling sequences. These calling sequences contain 
basically the same information as the original call to the I/O 
switch (ios_). Since the same interface module may be used to 
control several devices simultaneously, it is necessary that the 
I OS 1 M maintain separate data about the status of each device. It 
is the job of the interface module to create space for and 
maintain the individual device data, but it is the responsibility 
of the I/O switch to keep track of the stream, device, and device 
data associations. Device data is kept in a region called the 
Stream Data Block (SDB) and contains information describing the 
status of each device and other information for use by both the 
interface module and the 1/0 switch. As an example of device 
status information, consider the typewriter interface module, 
which maintains the channel number of the typewriter being 
accessed and the event ID of the event which is signalled when an 
interrupt of interest comes from this typewr i ter . Information 
shared by both the interface module and the switch is kept at the 
beginning of the SDB in a fixed format (discussed later in this 
section). This information consists of the name of the interface 
module and a list of names of devices or streams upon which I/O 
operations are to be performed for calls to this stream. Each 
call by the switch to an interface module has as an argument a 
pointer to the SDB for the stream referred to in this call. This 
SDB pointer is passed to the interface module by the I/O switch 
in addition to the arguments received by the I/O switch in the 
original call to the I/O system. 

Each interface module is called in a standard manner by the 
I/O switch. For the sake of efficiency, the calls to the 
interface module are directed through a transfer vector. Each 
interface module has a transfer vector. The transfer vector is 
an assembly language program consisting of a sequence of transfer 
instructions, each one transferring to a different entry in the 
corresponding interface module. The beginning of the transfer 
vector is identified by the external symbol whose name is formed 
by concatenating the name of the interface module and the string 
"module". The name of the transfer vector is the name of the 
interface module. The I/O switch calls a particular entry in an 
interface module by transferring to a particular location 
relative to the beginning of the transfer vector; therefore each 
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location in each transfer vector in the system corresponds to a 
particular entry in the interface module and is fixed by 
system-wide convention. A typical transfer vector is shown in 
Figure 1. Notice that some locations in the vector transfer to a 
small subroutine. This routine returns an error in the status 
argument indicating that this interface module does not contain 
this entry. Figure 2 shows a template transfer vector which 
shows the position of each interface module entry in the transfer 
vector. Note that since the name of the interface module is the 
name on the transfer vector, the name of the procedure the 
transfer vector transfers to must be distinct and not the name of 
the interface module. In Figure 1 this procedure is named 
typewr i ter__ut i 1_. There may, however, be several procedures 
involved, possibly each I/O system call being implemented by a 
separate program. 

For example, the transfer vector for the typewriter., 
interface module shown in Figure 1 contains the external symbol 
typewr i ter__modul e . When a call is made to this interface module, 
the I/O switch will transfer to an offset relative to the 
location corresponding to this external symbol. The specific 
offset depends upon the particular call being made. 

Each interface module is responsible for returning the 
proper status string. (See the MPM Reference Guide Section on 
the Use of the Input and Output System.) The first 36 bits 
(first word) of the status string is an error code. A 0 error 
code indicates no error. The error code may be either a standard 
Multics error code (see the MPM Reference Guide Section on System 
Error Codes and Meanings) or a bit string representing the status 
of a physical device. The latter case is used by Device 
Interface Modules (DIM) in physical mode and is indicated by the 
first bit of the status string being one. The exact 
interpretation of the physical status bits is dependent on the 
interface module in question. The next 18 bits indicate the 
state of the transaction. One of these bits is the so called det 
bit. If the interface module turns the bit on , the I/O switch 
will delete this device attachment. Normally, only the detach 
entry to the interface module turns the det bit on. The final 18 
bits of the status string is the transaction identification and 
is a unique string used to identify this transaction. The use of 
the transaction identification is not fully specifed yet and 
therefore should not be used. 

The attach entry of an I OS I M must perform certain tasks. 
The requested attachment may be a multiple attachment, i.e., an 
attempt to attach a device or stream on a stream to which some 
other device or stream is already attached. This may be detected 
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by the interface module by looking at the SDB pointer passed to 
it by the I/O switch. If the SDB pointer is not a null pointer / 
then an SDB already exists for this stream, indicating a multiple 
attachment. If the interface module does not allow multiple 
attachments, an appropriate error code must be returned in the 
status string. If the interface module does allow multiple 
attachments, or the SDB pointer passed by the sv/itch is null, 
then the interface module may proceed with the attachment. If a 
physical device is being attached, the interface module must call 
the I/O channel controller interface module to initialize the 
device. If a pseudo-device or intermediate interface module is 
involved, then whatever initialization that is appropriate must 
be performed. if no errors have occurred, the interface module 
must then update the information in the SDB. If this is the 
first attachment to this stream, then the interface module must 
allocate space for the SDB and return a pointer to the SDB to the 
switch by overwriting the null SDB pointer passed to it by the 
switch. One means of performing allocation is by using the PL/1 
allocate statement. In order that both the interface module and 
the I/O switch may share certain data, it is necessary that this 
data be kept in a fixed format (see Figure 3) at the beginning of 
the SDB. The shared data includes the name of the interface 
module and a list of the devices or streams to which this stream 
is attached. A list of device or stream names is necessary to 
allow multiple attachments which permit an I/O call to one stream 
to fan out to many devices or streams (i.e., broadcasting). This 
shared information is most easily allocated and updated by the 
interface module, but is needed by the switch in order that it 
may inform the user as to the name of the interface module and 
the devices or streams to which a particular stream is attached. 
Once the information in the SDB has been updated, the information 
in the status string argument must be updated and the interface 
module may then return to the switch. If an uncorrectable error 
occurs at any point in the attachment, the interface module 
should return an appropriate error code in the status string. If 
the interface module operates in physical mode, it may choose to 
return the physical status of the device involved in place of an 
error code. It indicates this by turning gn the first bit of the 
status string. If the attachment was not successful, and no 
other devices or streams are already attached to this stream, the 
SDB should be freed and the det bit of the status string should 
be turned on, indicating to the switch that the attachment should 
be destroyed. 

For most of the other types of I/O calls, the actions taken 
depend upon the device being referenced and the nature of the 
call. As an example, consider a read call to a stream that is 
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attached to a typewriter. The interface module must reference 
the device data pointed to by the SDB pointer supplied by the 
switch to retrieve the logical channel of this device. The IOSIM 
then calls the channel controller module to read in the data (the 
issue of buffering has been ignored for this example). If 
nothing is read, the IOSIM calls ipc_$block to wait for more 
input. Here it is again necessary to reference the device data 
to get the event identifier of the event which indicates that 
more input has arrived. This event identifier is passed to 
ipc_$block so that the process is awakened only upon the 
occurrence of this event. Upon begin awakened, the interface 
module again calls the channel controller interface module to 
read the data and then fills in the status string appropriately. 

In a detach call, the device must be terminated. For a 
physical device, this will require that the interface module call 
the channel controller module. In all cases, the interface 
module must update the status string and, if the detachment is 
successful and no other devices or streams are currently attached 
to this stream, deallocate the SDB and store a one in the det bit 
of the status string. Upon performing a detachment, the caller 
may not wish to completely terminate a device. For example, in 
detaching a tape, the caller may not wish to unload or even 
rewind the tape because it intends to continue using the tape. 
For this purpose, the detach call has a disposal argument. It is 
here that the caller may specify the extent to which the device 
is to be terminated. The default, i.e., a null string, is full 
termination. The effect of specifying any other disposal is 
dependent upon the interface module. 

Calling sequences for each interface module entry are fixed 
by system convention. The arguments for each entry are the same 
as the arguments to the I/O switch for the same entry with the 
following exceptions: 

1) The attach entry in the interface module contains an extra 
argument at the end of the argument list which is a pointer. On 
initial attachment on a stream, the interface module returns in 
this argument a pointer to the SDB it has allocated for this 
device. On all subsequent calls on this stream, the SDB pointer 
is passed back to the interface module. 

2) All other entries to the interface module have the SDB pointer 
as their first argument. The SDB pointer argument replaces the 
first argument in the calling sequence for the same entry in the 
I/O switch. 
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Exampl es 

Two entry statements in the typewriter outer module might be 
as f ol 1 ows : 

typewr i ter__attach: entry (stream, type, device, mode, 

status, data_ptr); 

typewr i ter_read : entry (data_ptr, workspace, offset, 

nelements, nactual, status); 
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"Interface Module Transfer Vector for the 
"typewr i ter_ Interface Module 

entry typewr i terjnodul e 

typewr i ter_modul e : 

tra *+l,6 go to proper transfer instruction 



tra 
tra 
tra 
tra 
tra 
tra 
tra 
tra 
tra 
tra 
tra 
tra 
tra 
tra 
tra 
tra 
tra 
tra 
tra 
tra 
tra 
tra 

tra 
tra 
tra 
tra 
tra 
tra 
tra 
tra 

end 



< typewr 

< typewr 
< typewr 

< typewr 
< typewr 
< typewr 
< typewr 

< typewr 
<ios_>| 
<ios_> | 

< typewr 
< typewr 

os_>| 
os_>| 
os_>| 
os_>| 
os_>| 
os_>| 
os_>| 
os_>| 
os_>| 
os_>| 

os_>| 
os_>| 
os_>| 
os_>| 
os_>| 
os_>| 
os_>| 
os_>| 



i ter__ut 
i ter_ut 
i ter_ut 
i ter__ut 
i ter__ut 
i ter_ut 
i ter_ut 
iter_ut 
\jio_ent ryj 
[no_ent ry] 
i ter_ut i 1_ 
i t e r_u t i 1 _ 
ill o_e n t r 
(no__ent ryj 
(no_ent ry] 
(no_ent ry) 
[no_ent r$ 
jno_ent rvj 
jno_ent rg 
{no_ent r$ 
|no__ent r$ 
(no_ent r^ 

(no_ent r$ 
|To_entr^] 
(no_ent r£[ 
jno_ent ry] 
jno_ent ryj 
£o_ent r^ 
jno__ent r^ 
{no_ent ry] 



> \ [typewr i ter_attachl 
.> I [typewr i ter__detacl3 
.> I jtypewr i ter_readl 
_> | typewr i ter__wr i t|| 
.> I jtypewr i ter_abor2 
.>| [typewr i ter_ordef| 
.> I (typewr i ter_reset reafl 
.> I \typewr i ter_resetwr i tej 
this entry not implemented 
this entry not implemented 
.> I [typewr i ter_setdel im[ 
.> I [typewr i ter_getdel im| 
this entry not implemented 
this entry not implemented 
this entry not implemented 
this slot currently unused 
this slot currently unused 
this slot currently unused 
this slot currently unused 
this entry not implemented 
this entry not implemented 
this slot currently unused 
this slot currently unused 
this slot currently unused 
this slot currently unused 
this slot currently unused 
this slot currently unused 
this slot currently unused 
this slot currently unused 
this slot currently unused 



Figure 1: A Typical Transfer Vector 
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"Interface Module Transfer Vector for the 
"xyz__ Interface Module 



entry 
xyz_modu! e: 

tra *+l / 6 



xyz_modul e 

go to proper transfer instruction 



tra 
tra 
tra 
tra 
tra 
tra 
tra 
tra 
tra 
tra 
tra 
tra 
tra 
tra 
tra 
tra 
tra 
t ra 
tra 
tra 
tra 
tra 
tra 
tra 
tra 
tra 
tra 
tra 
tra 
tra 



<xyz_ 
<xyz. 
<xyz. 
<xyz. 
<xyz. 
<xyz_ 
<xyz_ 
<xyz_ 
<xyz_ 
<xyz_ 
<xyz. 
<xyz_ 
<xyz_ 
<xyz_ 
<xyz_ 

< i o s_ 
<ios_ 

< ios_ 

< ios_ 
<xyz_ 
<xyz_ 

< ios_ 

< ios_ 

< ios_ 

< ios. 

< ios_ 

< ios_ 

< ios. 

< ios. 

< ios 



uti 
ut i 
uti 
ut i 
uti 
.uti 
ut i 
.uti 
ut i 
uti 
uti 
.ut i 
uti 
uti 
uti 



> | (no_ent ry] 

> I ffio_entry] 
>| jfio_entryJ 

> I jJ)o_entry] 
.ut i 1_> | (xyz_ 

ut ! 1 > | jxyz_j 

} I £no_ent r£ 

> | (no_ent ry 
>l jflo^entr^ 
>l [fto_entry 
>! jQo_en t 
} \ (no_entr£ 
>l Bp_entr£ 
>l (np_entry 

> | (no_entryJ 



.attacQ 
.detacQ 
.read] 
wr i tef 
.aborj 
.order} 
.reset rea^ 
.resetwr i tej 
.sets izej 
.gets i zej 
.setdel im] 
.get del i nil 
seeR] 
telfj 

.changemod^ 
this slot 
this slot 
this slot 
this slot 
.readsyncj 
wr i tesyncj 
this slot 

this slot 

this slot 

this slot 

this slot 

this slot 

this slot 

this slot 

this slot 



currently unused 
currently unused 
currently unused 
currently unused 



cur rent 1 y 

current ly 
cur rent 1 y 
cur rent 1 y 
current 1 y 
current 1 y 
current 1 y 
current 1 y 
current! y 



unused 

unused 
unused 
unused 
unused 
unused 
unused 
unused 
unused 



end 



Figure 2: A Template Transfer Vector 
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declare 1 s tream__ data_bl ock aligned based (sdb_poi nter ), 
2 outer_modul e_name char (52), 
2 dev i ce_name_l i st ptr, 

2 ; 



1) outer_jnodule_name 

2) dev i ce__name_J i s t 



3) 



is the name of the interface module. 

is a pointer to the threaded list of 
device names. 

the remaining information for this stream 
is at the discretion of the interface 
modul e , 



declare 1 device__name aligned based, 
2 next_ptr ptr, 
2 name__size fixed bin, 
2 name char (name_size) aligned; 



1) next__ptr 

2) name__size 
5) name 



is a pointer to the next entry. This is null 

if this is the last entry. 

is the number of characters in the name. 

is the name of the device or stream. 



Figure 3: Declaration for a Stream Data Block 
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ASCI I CHARACTER SET 

The Multics standard character set is the revised U.S. ASCII 
Standard (refer to USA Standards lnstitute / "USA Standard 
X3.U-1968") . The ASCM set consists of 128 seven bit characters. 
Internally these are stored right justified in four nine bit 
fields per word. The two high order bits in each field are 
expressly reserved for expansion of the character set; no system 
program shall use them. Any hardware device which is unable to 
accept or create the full character set should use established 
escape conventions for representing the entire set. It is 
emphasized that there are no meaningful subsets of the revised 
ASCII character set. 



Included in the ASCII character set 
graphics, 33 control characters, and the 
conventions assign precise interpretations to 
the space, and 11 of the control characters 



are 9k printing 
space. Multics 
all the graphics, 
One of these 



control characters is the "Enter Graphic Mode" character which 
is recognized only on a graphics device. The remaining 22 
control characters are presently reserved. The graphics in the 
set are as f ol 1 ows : 



Upper Case Al phabet 
ABCDEFGHI JKLMNOPQRSTUVWXYZ 
Digits 



Lowe r Case Al phabet 
abcdefgh i j klmnopqrstuvwxyz 



0123456789 
Special Characters 



exclamation point 

double quote 

number sign 

dollar sign 

percent 

ampersand 

acute accent 

left parenthesis 

right parenthesis 

aster i sk 

plus 

comma 

mi nus 

per iod 

right slant 

colon 



; semicolon 
< less than 
= equals 
> greater than 
? question nark 
y commercial at 
I left bracket 
\ left slant 
3 right bracket 
a c i rcumf 1 ex 
_ underl ine 

grave accent 
£ left brace 
; vert i cal line 
} right brace 

t i 1 de 
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Control Characters 

The following conventions define the standard meaning of the 
ASCII control characters which are given precise interpretations 
in Multics. These conventions will be followed by all standard 
Device Interface Modules (DIM) and by all system software inside 
the I/O system interface. Since some devices have different 
interpretations for some characters, it is the responsibility of 
the appropriate DIM to perform the necessary translations. 

The characters designated as "not used" are specifically 
reserved and may be assigned definitions at any time. Until 
defined, "not used" control characters will be output using the 
octal escape convention in normal output and not printed in 
edited mode. Users wishing to assign interpretations for a "not 
used" character must use a non-standard DIM. 

If a device does not perform a function implied by a control 
character, its standard DIM will provide a reasonable 
interpretation for the character on output. This may be 
substituting one or more characters for the one, or printing an 
octal escape, or ignoring it. 

The Multics standard control characters are: 

BEL Sound an audible alarm. 

BS Backspace. Move the carriage back one space. The backspace 
character implies overstrike rather than erase. 

HT Horizontal tab. Move the carriage to the next horizontal 
tab stop. Multics standard tab stops are at 11, 21, 31... 
when the first column is numbered 1. This character is 
defined not to appear in a canonical string. 

NL "New line". Move the carriage to the left end of the next 
line. This implies a carriage return plus a line feed. 
ASCII LF (octal 012) is used for this character. 

VT Vertical tab. Move the carriage to the next vertical tab 
stop and to the left of the page. Standard tab stops are at 
lines 11, 21, 31... when the first line is numbered 1. 
This character is defined not to appear in a canonical 
st r i ng. 

NP New page. Move the carriage to the top of the next page and 
to the left of the line. ASCII FF (octal Qlh) is used for 
this character. 



@ Copyright, 1971, Massachusetts Institute of Technology 
Ail r S gh ts reserved . 



MULTICS PROGRAMMERS' MANUAL 



5.1 



ASC I I Character Set 
Standard Data Formats and Codes 

Page 3 



i n / ^ i. i -7 t 
XU/ 14/ / X 



CR Carriage return. Move the carriage to the left of the 
current line. This character is defined not to appear in a 
canonical string. 

RRS Red ribbon shift. ASCII SO (octal 016) is used for this 
character . 

BRS Black ribbon shift. ASCII SI (octal 017) is used for this 
character . 

PAD Padding character. This is used to fill out words which 
contain fewer than four characters and which are not 
accompanied by character counts. This character is 
discarded when encountered in an output line and cannot 
appear in a canonical character string. ASCII DEL (octal 
177) is used for this character. 



Non-Standard Control Character 

One control character is recognized under certain conditions 
by all DIMs because of its wide use outside Multics. This 
character is handled specially only when the DIM is printing in 
edited mode/ i.e., it is ignoring unavailable control functions. 
This character is 



NUL Null character. ASCII character NUL (octal 000) is used for 
this purpose. In normal mode, this character is printed 
with an octal escape sequence; in edited mode, it is treated 
exactly as PAD. This character cannot appear in a canonical 
character string. 

Programmers are warned against using NUL as a routine 
padding character and using edited mode on output because all 
strings of zeros, including mistakenly uninitialized strings, 
will be di scarded . 



Graphic Control Characters 

Character code 037 octal (ASCII US) is used to escape into 
graphic output mode when a graphic display terminal is in use; 
it is treated as "not used" and an octal escape is provided when 
an ordinary typewriter is in use. Details on Multics graphic 
output mode may be found in the Graphic Users' Supplement to the 
MPM. 
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Not Used Characters 

These characters are 



SOH 


001 


ACK 


006 


STX 


002 


DLE 


020 


ETX 


003 


DC1 


021 


EOT 


OOU 


DC2 


022 


ENQ 


005 


DC3 


023 
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for future use: 



DC** 


02U 


EM 


031 


NAK 


025 


SUB 


032 


SYN 


026 


ESC 


033 


ETB 


027 


FS 


03t* 


CAN 


030 


GS 


035 






RS 


036 



Notes 

The vertical line has two representations on current console 
devices. It may be represented as either a solid vertical line 
(|) or a broken vertical line (} ). These are represented 
identically internally by octal value 17k. 
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ASCII Character Set on Multics 





u 


i 


Z 


3 




r 
D 


n 
0 


7 


000 


(NUL) 














BEL 


010 


BS 


HT 


NL 


VT 


NP 


CR 


RRS 


BRS 


020 


















030 
















EGM 


QkO 


Space 


i 


1 1 


# 


$ 






M 
W 


050 


( 


) 


* 


+ 






• 


1 


060 


0 


1 


2 


3 




5 


6 


7 


070 


8 


9 


• 




< 




> 




100 


@ 


A 


B 


C 


D 


E 


F 


G 


110 


H 


1 


J 


K 


L 


M 


N 


0 


120 


P 


Q 


R 


S 


T 


U 


V 


w 


130 


X 


Y 


Z 


t 


\ 


1 


A 




11*0 




a 


b 


c 


d 


e 


f 


g 


150 


h 


i 


j 


k 


1 


m 


n 


o 


160 


P 


q 


r 


s 


t 


u 


V 


w 


170 


X 


y 


z 


i 


i 
f 


} 


/NX 


PAD 
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ag« 



Mul t 


i cs Def i n i t i ons 






NUL 


Null character (edited output 


mode 


onl y ) 


BEL 


Al arm 






BS 


Backspace 






NT 


Horizontal Tab 






ML 


New Line (carriage return and 


1 i ne 


feed) 


VT 


Vertical Tab 






NP 


New Page (carriage return and 


form 


feed) 


CR 


Carriage Return 






RRS 


Red Ribbon Shift 






BRS 


Black Ribbon Shift 






EGM 


Enter Graphic Mode 






PAD 


Padding Character 
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PUNCHED CARD CODES 

This write-up defines standard card punch codes to be used 
in representing ASCII characters for use with Multics. Since the 
card punch codes are based on the punch codes defined for the IBM 
EBCDIC standard, a correspondence between the EBCDIC and ASCII 
character sets is defined automatically. 

Notes 

The Multics standard card punch codes described here are not 
identical to the currently proposed ASCII punched card code. The 
proposed ASCII standard code is not supported by any currently 
available punched card equipment; until such support exists, it 
is not a practical standard for Multics work. The Multics 
standard card punch code described here is based on the widely 
available card handling equipment used with IBM System/360 
computers. The six characters for which the Multics standard 
card code differs from the ASCII card code are noted in the table 
below. 

EBCDIC and ASCI I 

The character set used for symbolic source programs and 
input/output on Multics is the American National Standard Code 
for Information Interchange, X3. 4-1968, known as ASCII. This set 
is described in the MPM Reference Guide section, ASCII Character 
Set. 

Similarly, the character set used for input/output with some 
devices from a System/360 computer is the IBM standard, known as 
EBCDIC. This set is described on page 150.3 of the IBM Systems 
Reference Library Manual "IBM System/360 Principles of 
Operation", A22-6821-7. 

EBCDIC is an eight-bit code for which graphics* have been 
assigned to 88 code values, controls to 51 code values, and card 
codes to all 256 possible values. ASCII is a seven-bit code with 
graphics assigned to 9k code values and controls to 34. 



* By way of terminology, the characters are divided into two 
groups, named graphics and controls (including the space). 
The graphics are further divided into alphabetic (upper and 
lower case), numeric, and special subgroups. 
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Although there are 85 graphics in common between EBCDIC and 
ASCII, there is no practical algorithm by which one can deduce an 
EBCDIC code value from the ASCII code value (or vice versa), 
short of a complete table look-up. That is to say, the numerical 
values of the two codes are more or less completely unrelated. 

Graph i c Correspondence 

On the other hand, since there are so many common graphics, 
one can define a correspondence between at least the graphic 
parts of the two codes, and thereby establish conventions for 
communication between computers using the codes. Simultaneously, 
a card punch code for ASCII is defined, as mentioned above, that 
has the practical advantage of equipment available in quantity 
using these card codes. Table 1 provides this correspondence as 
used on Mul tics. 

In interpreting Table 1, it is helpful to observe that the 
correspondence between ASCII Code Value in column one and ASCII 
Meaning in column two is firmly defined by the ASCII standard. 
Similarly, correspondence among Corresponding EBCDIC Meaning in 
column three, EBCDIC Code Value in column four, and 
EBCD I C/Mu 1 t i cs Punch Code in column five is firmly defined by the 
IBM standard. This table provides a correspondence between the 
first two columns on the one hand, and the last three on the 
other hand, based on graphic similarities and other suggestions, 
as noted. 

The graphic correspondence in Table 1 is derived as follows: 
85 ASCII graphic characters correspond directly with identical 
EBCDIC graphics. Three ASCII graphics are made to correspond 
with the three remaining EBCDIC graphics as follows: 



Thus all 88 EBCDIC graphics have an equivalent ASCII graphic. 
The remaining six ASCII graphics, namely: 

left and right square brackets 

left and right braces 
grave accent 
over 1 i ne (til de) 



AS CI I 



EBCDIC 



acute accent 
left slant 
ci rcumf 1 ex 



apostrophe 
cent sign 
nega t i on 
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have no EBCDIC graphic equivalent. In Table 1 they are made to 
correspond to unassigned EBCDIC codes which, never thel ess, have 
well-defined card punch code equivalents. Where possible, the 
unassigned EBCDIC codes chosen result in the same punch card 
representation as in the proposed ASCII standard card code. Thus 
a majority of the Multics standard card codes do, in fact, agree 
with the proposed standard. 

The programmer faced with the problem of representing ASCII 
data in the EBCDIC environment must make some arbitrary decisions 
if he needs to obtain graphic representation of these six 
characters. One appropriate technique is that the suggested 
"illegal" code be used wherever EBCDIC code representation is 
required (e.g., in cards or in core memory), but, when printing 
readable output, the illegal codes be printed as escapes or 
over str i kes. 

For example, choosing the cent sign as an escape character. 



one has the following graphic representation borrowed from 


Multics conventions. 




ASCII Graphic 


EBCDIC Escape Representation 


left brace 


c( 


right brace 


c) 


ti lde 


Ct 


left accent 


c' 


left bracket 




right bracket 


c> 


left slant 


£131* 


The last escape is 


required in order to insure unambiguous 



meaning of the cent sign as an escape character. 

Alternatively, one can propose a series of overstrike 
graphics which are more suggestive of the ASCII graphics being 
represented. For example, 

ASCI I Graph! c EBCDIC Overstri ke Representation 

left brace 4 (left parenthesis over minus sign) 

right brace * (right parenthesis over minus sign) 

left bracket # (left parenthesis over equals sign) 

right bracket # (right parenthesis over equals sign) 

grave accent 1 (apostrophe over minus sign) 

tilde n (double quote over negation sign) 
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These two alternatives suggested for printing readable 
output in an EBCDIC environment are mirrored in the Multics card 
input conventions (based on card punching with EBCDIC equipment). 
Either the multicolumn escape sequences described above or the 
single column multiple punch codes (with meaningless graphics 
printed on the card, of course) can be used to represent these 
characters . 

Control Character Correspondence 

The 3k ASCII control characters and 51 EBCDIC control 
characters match in 33 cases. The remainder have no 
correspondence that can be expected to work in most cases. 

As a result, the programmer transforming character data from 
one environment to another must study the precise meaning of the 
control codes in the new environment. For example, some EBCDIC 
control codes might logically transform into ASCII hardware 
escape sequences for some hardware devices. Other controls might 
not be imi table in the new environment and might instead be 
printed with graphic escape sequences, or possibly ignored. 

Since, in general, it is awkward to hand punch the card 
codes which correspond to the controls, it should be noted that 
for Multics input, control codes can be punched as graphic octal 
escape sequences. Also, the end of a card is interpreted as a 
new line character. 

Ei ght-Bi t Envi ronment 

In the System/360 Manual, "Principles of Operation", there 
is published a code table labeled USASCI I -ei gh t. This table 
purports to show how the seven-bit ASCII code is represented in 
an eight-bit environment. It is obtained by taking ASCII, 
interchanging bits 6 and 7, and duplicating bit 7 as bit 8. This 
method of representing ASCII in an eight-bit environment is not 
an ANSI standard but rather an IBM suggestion (resulting from a 
nine-track tape design problem) which has no official sanction. 
The ANSI standard way of representing ASCII code in an eight-bit 
environment is by setting bit 8 to zero. (See, for example, USAS 
X3. 22-1967, paragraph 6.4.3, describing nine-track tape 
standards.) In any case, the Multics standard for representation 
of ASCII codes in the nine-bit environment of the Honeywell 6180 
is seven-bit codes right adjusted in nine-bit fields, with 
leading zeros. 
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Table 1: Correspondence Between 
ASCII Characters and EBCDIC Characters 



ASCI 1 
Code 
Val ue 


ASCI 1 
Meani ng 


Corre- 
spond! ng 
EBCDI C 
Meani ng 


EBCDIC 
Code 
Val ue 


EBCDIC/ Comments 

Mul tics 

Punch 

Code 


000 


(NUL) 


NUL 


00 


9-12-0-8-1 


001 


(SOH) 


SOH 


01 


9-12-1 


002 


(STX) 


STX 


02 


9-12-2 


003 


(ETX) 


ETX 


03 


9-12-3 


00k 


(EOT) 


EOT 


37 


9-7 


005 


( ENQ) 


ENQ 


20 


9-0-8-5 


006 


(ACK) 


ACK 


2E 


9-0-8-6 


007 


BEL 


BEL 


2F 


9-0-8-7 


010 


BS 


BS 


16 


9-11-6 


011 


HT 


HT 


05 


9-12-5 


012 


NL(LF) 


HI 


15 


9-11-5 (Note 1) 


013 


VT 


VT 


0B 


9-12-8-3 


Oil* 


NP(FF) 


FF 


0C 


9-12-8-4 


015 


(CR) 


CR 


0D 


9-12-8-5 


016 


RRS(SO) 


SO 


0E 


9-12-8-6 


017 


BRSCSI ) 


SI 


OF 


9-12-8-7 


020 


(DLE) 


DLE 


10 


12-11-9-8-1 


021 


(DC1) 


DC1 


11 


9-11-1 



ASCII code values are in octal; EBCDIC code values are 
in hexadecimal. 
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ASCII ASCII Corre- 

Code Meaning sponding 

Value EBCDIC 

Meani ng 



EBCDIC EBCDIC/ Comments 
Code Multics 
Value Punch 
Code 



022 


HLF( DC2 ) 


DC2 


023 


(DC3) 


TM 


021* 


HLRCDC4) 


DC4 


025 


(NAK) 


NAK 


026 


(SYN) 


SYN 


027 


(ETB) 


ETB 


030 


<CAN) 


CAN 


031 


(EM) 




032 


(SUB) 


SUB 


U J J 


V C Ok, 1 


CO Kt 


034 


(FS) 


IFS 


035 


(GS) 


1 GS 


036 


<RS) 


IRS 


037 


(US) 


1US 


040 


Space 


Space 


041 


i 

• 


! 


042 


it 


it 


043 


# 


# 


044 


$ 


$ 



12 9-11-2 

13 9-11-3 (Note 3) 
3C 9-8-4 

3D 9-8-5 

32 9-2 

26 9-0-6 

18 9-11-8 

19 9-11-8-1 
3F 9-8-7 

27 9-0-7 

1C 9-11-8-4 

ID 9-11-8-5 

IE 9-11-8-6 

IF 9-11-8-7 

40 Oio punches) 

5a 11-8-2 (Note 1) 

7F 8-7 

7B 8-3 

5B 11-8-3 



ASCII code values are in octal; EBCDIC code values are 
in hexadecimal. 
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ASCII ASCII Corre- EBCDIC EBCDIC/ Comments 

Code Meaning spondlng Code Multics 

Value EBCDIC Value Punch 

Meaning Code 



045 % % 6C 0-8-1* 

046 & & 50 12 

01*7 ' . * 7D 8-5 Maps ASC I I 

accute accent 



050 ( ( i*D 12-8-5 

051 ) ) 50 11-8-5 

052 * * 5C ll-8-l* 

053 + + 4E 12-8-6 
051* , / 6B 0-8-3 

055 - - 60 11 

056 . . i*B 12-8-3 

057 / / 61 0-1 

060 0 0 F0 0 

061 1 1 Fl 1 

062 2 2 F2 2 

063 3 3 F3 3 
061* 1* h Ft* i* 

065 5 5 F5 5 

066 6 6 F6 6 



into EBCDIC 
apostrophe 



ASCII code values are in octal; EBCDIC code values are 
i n hexadecimal . 
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ASCII ASCII Corre- EBCDIC EBCDIC/ Comments 

Code Meaning sponding Code Multics 

Value EBCDIC Value Punch 

Meaning Code 



067 


7 


7 


F7 


7 


070 


8 


8 


F8 


8 


071 


Q 


q 


PQ 


q 


072 


• 


• 
• 


7A 


o _ o 


073 


• 


• 

/ 


J u 


11 -S-.fi 
XX O D 


07U 


< 


< 


kC 


12-8-U 


075 






7E 


8-6 


076 


> 


> 


6E 


0-8-6 


077 


? 


? 


6F 


0-8-7 


inn 

xUU 


C\ 

13 






8-4 


101 


A 


A 


CI 


12-1 


102 


B 


B 


C2 


12-2 


103 


C 


C 


C3 


12-3 


10U 


D 


D 


CU 


12-U 


105 


E 


E 


C5 


12-5 


106 


F 


F 


C6 


12-6 


107 


G 


G 


C7 


12-7 


110 


H 


H 


C8 


12-8 


111 


1 


1 


C9 


12-9 



ASCII code values are in octal; EBCDIC code values are 
i n hexadeci ma 1 . 
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ASCII ASCII Corre- EBCDIC EBCDIC/ 

Code Meaning sponding Code Multics 

Value EBCDIC Value Punch 

Meaning Code 



Comments 



112 


J 


J 


Dl 


11-1 


113 


K 


K 


D2 


11-2 


Ilk 


L 


L 


D3 


11-3 


115 


M 


M 


DU 


ll-l* 


116 


N 


N 


D5 


11-5 


117 


0 


0 


D6 


11-6 


120 


P 


P 


D7 


11-7 


121 


Q 


Q 


D8 


11-8 


122 


R 


R 


D9 


11-9 


123 


S 


S 


E2 


0-2 


121* 


T 


T 


E3 


0-3 


125 


U 


U 


Ei» 


0-h 


126 


V 


V 


E5 


0-5 


127 


w 


w 


E6 


0-6 


130 


X 


X 


E7 


0-7 


131 


Y 


Y 


E8 


0-8 


132 


Z 


Z 


E9 


0-9 


133 


[ 


None 


8D 


12-0 



as £<. 
(Notes 1,2) 



ASCII code values are in octal; EBCDIC code values are 
i n hexadeci mal . 
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13k \ t kA 

135 ] None 9D 

136 5F 

137 6D 
IkO v None 79 

Ihl a a 81 

1^2 b b 82 

143 c c 83 

lkk d d 84 

11*5 e e 85 

11*6 f f 86 

147 g g 87 

150 h h 88 

151 i i 89 
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12-8-2 Maps ASCI I left 
slant into 
EBCDIC cent sign. 
Used as an escape. 
(Note 1) 

12-11-8-5 May be punched 
as £>. 
(Notes 1,2) 

11- 8-7 Maps ASCI I 

c i rcumf 1 ex 
into EBCDIC 
negat i on. 

0-8-5 

8-1 May be punched 

as £\ (Note 2) 

12- 0-1 
12-0-2 
12-0-3 
12-0-1* 
12-0-5 
12-0-6 
12-0-7 
12-0-8 
12-0-9 



EBCDIC EBCDIC/ Comments 

Code Multics 
Value Punch 
Code 



ASCII code values are in octal; EBCDIC code values are 
i n hexadecimal . 
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ASCII ASCII Corre- EBCDIC EBCDIC/ Comments 

Code Meaning spondlng Code Multics 

Value EBCDIC Value Punch 

Meaning Code 



152 


j 


j 


91 


12-11-1 


153 


k 


k 


92 


12-11-2 


15 4 


1 


1 


95 


12-11-3 


155 


m 


m 


94 


12-11-4 


156 


n 


n 


9 5 


12-11-5 


157 


o 


o 


96 


12-11-6 


160 


P 


P 


97 


12-11-7 


161 


q 


q 


98 


12-11-8 


162 


r 


r 


99 


12-11-9 


163 


s 


s 


A2 


11-0-2 


164 


t 


t 


A3 


11-0-3 


165 


u 


u 


A4 


11-0-4 


166 


V 


V 


A5 


11-0-5 


167 


w 


w 


A6 


11-0-6 


170 


X 


X 


A7 


11-0-7 


171 


y 


y 


A8 


11-0-8 


172 


z 


z 


A9 


11-0-9 


173 


i 


None 


CO 


12-0 


174 


1 
1 


1 


4F 


12-8-7 



May be punched 
as c(. (Note 2) 

(Note 1) 



ASCII code values are in octal; EBCDIC code values are 
in hexadecimal. 
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EBCDIC 

Code 

Value 



EBCDIC/ 
Mul t i cs 
Punch 
Code 



Comments 



175 
176 
177 



} None 
~ None 
PAD(DEL) DEL 



DO 
Al 
07 



11-0 



May be punched 
as £). (Note 2) 



11- 0-1 May be punched 

as ct. (Note 2) 

12- 7-9 



Note 1: In the punched card code proposed for ASCII in 
reference 5), a different card code is used for this 
character . 

Note 2: This graphic does not appear in (or map into any 
graphic which appears in) the EBCDIC set; it is 
assigned to an otherwise illegal EBCDIC code value/card 
code combination. 

Note 3: In some applications/ the ASCII meaning of this control 
character may not correspond to the EBCDIC meaning of 
the corresponding control character. 

Where the Mul tics meaning of a control character differs from the 
ASCII meaning, the ASCII meaning is given in parentheses. 
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Table 2: Summary of Extensions to EBCDIC 
to Obtain Multics Standard Codes 



ASCI I 
Character 



Unassigned 
EBCDIC Card 
Code Chosen 



open bracket 


12- 


■0- 


8-5 




left slant 


12- 


•8- 


2 




close bracket 


12- 


-11 


-8-5 




grave accent 


8-] 


L 




* 


open brace 


12- 


■0 




* 


close brace 


11- 


-0 




* 


overl i ne/ti lde 


11- 


-0- 


1 




acute accent 


8-5 






* 


ci rcumf 1 ex 


11- 


-8- 


7 


* 



Same as the ASCII choice for this graphic 



Table 3: Summary of Differences Between Multics Standard 
Card Codes and Proposed ASCII Standard Card Codes 



ASCI I 
Character 



Mul t i cs 
Standard 
Card Code 



ASCI \ 
Standard 
Card Code 



new 1 i ne 

exclamation point 
open bracket 
left slant 
close bracket 
vertical line 



11-9-5 

11- 8-2 

12- 0-8-5 
12-8-2 
12-11-8-5 
12-8-7 



0-9-5 
12-8-7 
12-8-2 
0-8-2 

11- 8-2 

12- 11 
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MULT ICS STANDARD MAGNETIC TAPE FORMAT 

This write-up describes the standard physical format to be 

used on 7-track and 9-track magnetic tapes on Multics. Any 

magnetic tape not written in the standard format described here 
is not a Multics standard tape. 

Standard Tape Format 

The first record on the tape following the beginning of tape 
(BOT) mark is the tape label record. Following the tape record 
is an end of file (EOF) mark. Subsequent reels of a multireel 
sequence also have a tape label followed by EOF. (An EOF mark is 
the standard sequence of bits on a tape that is recognized as an 
EOF by the hardware.) 

Following the tape label and its associated EOF are the data 
records. An EOF is written after every 128 data records with the 
objective of increasing the reliability and efficiency of reading 
and positioning within a logical tape. Records that are repeated 
because of transmission, parity, or other data alerts, are not 
included in the count of 128 records. The first record following 
the EOF has a physical record count of 0 mod 128. 

An end of reel (EOR) sequence is written at the end of 
recorded data. An EOR sequence is: 

EOF mark 

EOR record 

EOF mark 

EOF mark 

Standard Record Format 

Each physical record consists of a 1024-word (36864-bit) 
data space enclosed by an 8-word header and an 8-word trailer. 
The total record length is then 1040 words (37440 bits). The 
header and trailer are each 288 bits. This physical record 
requires 4680 frames on 9-track tape and 6240 frames on 7-track 
tape. This is approximately 5.85 inches on 9-track tape at 800 
bpi and 7.8 inches on 7-track tape at 800 bpi, not including 
interrecord gaps. (Record gaps on 9-track tapes are 
approximately 0.6 inches and on 7-track tapes are approximately 
0.75 inches, at 800 bpi.) 
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For 1600 bpi 9-track tape / 
approximately 2.925 inches (with an 
approximately 0.5 inches). 



the record length is 
interrecord gap of 



Physical Record Heacjer 

The following is the format of the physical record header: 

octal representation 



Word 1: 
Words 2 and 3 

Word k: 



Word 5 



Word 6 



Constant with 
6703U355245. 



Multics standard unique identifier (70 bits, 
left justified). Each record has a different 
unique identifier. 

Bits 0-17: the number of this physical record 
in this physical file, beginning with record 
0. 

Bits 18-35: the number of this physical file 
on this physical reel, beginning with file 0. 



Bits 0-17: the number of data bits 
data space, not including padding. 



i n the 



Bits 18-35: the total number of bits in the 
data space. (This should be a constant equal 
to 36864.) 

Flags indicating the type of record. Bits 
are assigned considering the leftmost bit to 
be bit 0 and the rightmost bit to be bit 35. 
Word 6 also contains a count of the rewrite 
attempt, if any. 

BjjL Meaning Lf Bit is l 

0 This is an administrative record 
(one of bits 1 through 13 is 1). 

1 This is a label record. 

2 This is an end of reel (EOR) record. 
3-13 Reserved. 

Ik One or more of bits 15-26 are set. 
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Word 7: 



Word 8: 



15 This record is a rewritten record. 

16 This record contains padding. 

17 This record was written following a 
hardware end of tape (EOT) condition. 

18 This record was written synchronously; 
that is control did not return to the 
caller until the record was written 
out . 

19 The logical tape continues on another 
reel (defined only for an end of reel 
record) . 

20-26 Reserved. 

27-35 If bits lk and 15 are 1, this quantity 
indicates the number of the attempt to 
rewrite this record. If bit 15 is 0, 
this quantity must be 0. 

Contains the checksum of the header and 
trailer excluding word 7; i.e., excluding the 
checksum word. (See the MPM Reference Guide 
section, Standard Checksum, for a description 
of standard checksum computation.) 



Constant with octal 
51255611*6073. 



represen tat i on 



Physical Record Trailer 

The following is the format of the trailer: 

octal 



Word 1: 
Words 2 and 3 
Word h: 



Constant with 
107it63U22532. 



representat ion 



Standard Multics unique identifier (duplicate 
of header). 

Total cumulative number of data bits for this 
logical tape (not including padding and 
administrative records). 
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Word 5: 
Word 6: 



Word 7: 
Word 8: 



Padding bit pattern (described below). 

Bits 0-11: reel sequence number (multireel 
number), beginning with reel 0. 

Bits 12-35: physical file number, beginning 
with physical file 0 of reel 0. 

The number of the physical record for this 
logical tape, beginning with record 0. 



Constant with 
265221631704. 



octal 



representat ion 



Note: The octal constants listed above were chosen to form 

elements of a single-error-correcting code whether read as 8-bit 

tape characters (9-track tape) or as 6-bit tape characters 
(7-track tape). 



Administrative Records 

The standard tape format includes two types of 
administrative records: 1) a tape label record; or 2) an EOR 
record. 



The administrative records are of standard length: 8-word 
header, 1024-word data area, and 8-word trailer. 

The tape label record is written in the standard record 
format. The data space of the tape label record contains: 

Words 1-8: 32-character ASCII installation code. This 

identifies the installation that labelled the 
tape. 

Words 9-16: 32-character ASCII reel identification. This is 
the reel identification by which the operator 
stores and retrieves the tape. 



The remaining words are a padding pattern. 



The end of reel record contains only padding bits in its 
data space. The standard record header of the EOR record 
contains the information that identifies it as an EOR record 
(word 5, bits 0 and 2 are 1). 
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Densi tv ajid Pari tY 

Both 9-track and 7-track standard tapes are recorded in 
binary mode with odd ones having lateral parity. Standard 
densities are 800 frames per inch (bpi) (recorded in NRZI mode) 
and 1600 bpi (recorded in PE mode). 

Data Padding 

The padding bit pattern is used to fill administrative 
records and the last data record of a reel sequence. 

Wri te Error Recovery 

Multics standard tape error recovery procedures differ from 
the past standard technique in that no attempt is made to 
backspace the tape on write errors. If a data alert occurs while 
writing a record, the record is rewritten. If an error occurs 
while rewriting the record, that record is again rewritten. As 
many attempts as desired can be made to write the record. No 
backspace record operation is performed. 

The above write error recovery procedure is to be applied to 
both administrative records and data records. 

Compatibj 1 i tY Consideration 

Software shall be capable of reading Multics Standard tapes 
that are written with records with less than 102^ words in their 
data space. In particular, a previous Multics standard tape 
format specified a 256-word (9216-bit) data space in a tape 
record. 
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MULTICS STANDARD DATA TYPE FORMATS 



This section describes 
standard data types. See 



the representation of Multics 
the MPM Reference Guide section 
Calling Sequences for a discussion of data 
descriptors. in the following discussion let p be the declared 
precision of an arithmetic datum. Let n be the declared length 
of a string datum, and let k be the declared size of an area 
datum. 



Any scaling factor declared for a fixed-point 
stored with the datum. The scaling factor is 
value of the datum when the value participates in 
or conversion. 

Real Fixed-Point Binary Short (descriptor type 1) 

A real/ fixed-point/ binary, unpacked datum 
0<p<36 is represented as a 2's complement, 
stored in a 36-bit word. 

A real, fixed-point, binary, packed datum 
0<p<36 is represented as a 2's complement, 
stored in a string of p+1 bits. 

Real Fixed-Point Binary Long (descriptor type 2) 

A real, fixed-point, binary, unpacked datum 
35<p<72 is represented as a 2's complement, 
stored in a pair of 36-bit words the first of 
even address. 



datum is not 
appl i ed to the 
a computation 



of precision 
binary integer 



of precision 
binary integer 



of precision 
binary integer 
wh i ch has an 



A real, fixed-point, binary, packed datum of precision 
35<p<72 is represented as a 2's complement, binary integer 
stored in a string of p+1 bits. 

Real Floating-Point Binary Short (descriptor type 3) 



A real 
0<p<28 
and a 
36-bit 



floating-point, binary, 
is represented as a 2 1 
2 f s complement, binary 
word of the form: 



unpacked datum of precision 
s complement, binary fraction m 
integer exponent e stored in a 



m 



0 78 



35 



The value 0 is represented by m=0 and e--128. 
values, m satisfies l/2<Jm|<l. 



For all other 
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A real/ floating-point/ 
0<p<28 is represented 
and a 2's complement/ 
str i ng of p+9 b i ts . 



b i nary, 
t 



packed datum of 



prec i s i on 

as a 2's complement/ binary fraction m 
binary, integer exponent e stored in a 



m 



78 



p+8 



The value 0 is represented by m=0 and e=-128 
values/ m satisfies l/2<.|m|<l. 



For all other 



A real, floating-point/ binary, unpacked datum of precision 
27<p<6U is represented as a 2 f s complement/ binary fraction 
m and a 2's complement/ binary/ integer exponent e stored in 
a pair of 36-bit words the first of which has an even 
address. 



0 78 



m 



71 



The value 0 is represented by m=0 and e=-128. For all other 
values, m satifies l/2<.|ml<l. 

A real/ floating-point/ binary/ packed datum of precision 
27<p<6U is represented as a 2's complement/ binary fraction 
m and a 2's complement/ binary, integer exponent e stored in 
a string of p+9 bits. 

I el m 1 

0 78 p+8 

The value 0 is represented as m=0 and e=-128. For all other 
values, m satisfies l/2<Jm|<l. 

Complex Fixed-Point Binary Short (descriptor type 5) 

A complex, fixed-point/ binary, unpacked datum of precision 
0<p<36 is represented as a pair of 2's complement, binary 
integers stored in a pair of 36-bit words the first of which 
has an even address. The first integer is the real part of 
the complex value and the second integer is the imaginary 
part of the complex value. 

A complex, fixed-point, binary, packed datum of precision 
0<p<36 is represented as a pair 2's complement, binary 
integers stored in a string of 2(p+l) bits. The first p+1 
bits contain the integer representation of the real part and 
the second p+1 bits contain the integer representation of 
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the imaginary part. 

Complex Fixed-Point Binary Long (descriptor type 6) 

A complex, fixed-point, binary, unpacked datum of precision 
35<pS< IS REPRESENTED AS A PAIR OF < f s complement, binary 
integers stored in k consecutive 36-bit words the first of 
which has an even address. The first two words contain the 
integer representation of the real part and the last two 
words contain the integer representation of the imaginary 
part. 

A complex, fixed-point, binary, packed datum of precision 
35<p<72 is represented as a pair of 2* s complement, binary 
integers stored in a string of 2(p+l) bits. The first p+1 
bits contain the integer representation of the real part and 
the last p+1 bits contain the integer representation of the 
imaginary part. 

Complex Floating-Point Binary Short (descriptor type 7) 

A complex, floating-point, binary, unpacked datum of 
precision 0<p<28 is represented as a pair of real, 
floating-point, binary, unpacked data stored in two 36-bit 
words the first of which has an even address. The first 
word contains the real part of the complex value and the 
second word contains the imaginary part of the complex 
value. 

A complex, floating-point, binary, packed datum of precision 
0<p<28 is represented as a pair of real, floating-point, 
binary, packed data stored in a string of 2(p+9) bits. The 
first p+9 bits contain the real part of the complex value 
and the last p+9 bits contain the imaginary part of the 
complex value. 

Complex Floating-Point Binary Long (descriptor type 8) 

A complex, floating-point, binary, unpacked datum of 
precision 27<p<6U is represented as a pair of real, 
floating-point, binary, unpacked data stored in h 
consecutive 36-bit words the first of which has an even 
address. The first two words contain the real part of the 
complex value and the last two words contain the imaginary 
part of the complex value. 
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A complex, floating-point, binary, packed datum of precision 
27<p<6U is represented as a pair of real, floating-point, 
binary, packed data stored in 2(p+9) bits. The first p+9 
bits contain the real part of the complex value and the last 
P+9 bits contain the imaginary part of the complex value. 



Real Fixed-Point Decimal (descriptor type 9) 



A real, fixed-point, decimal datum (packed or unpacked) of 
precision p is represented as a signed, decimal integer 
stored as a string of p+1 characters. The leftmost 
character is either a "+" or a and all other characters 

are from the set "0123U56789" . 



An unpacked, decimal datum is aligned on a word boundary and 
occupies an integral number of words, some bytes of which 
may be unused. 

i $ i dn dz\ ~ i din 



Real Floating-Point Decimal (descriptor type 10) 



A real, floating-point, decimal datum (packed or unpacked) 
of precision p is represented as a signed, decimal integer m 
and a 2's complement, binary, integer exponent e stored as a 
string of characters of the form: 




The exponent e is right justified within 
character and the unused bit is zero. 



the last 9-bit 



An unpacked, decimal datum is aligned on a word boundary and 
occupies an integral number of words, some bytes of which 
may be unused. 



Complex Fixed-Point Decimal (descriptor type 11) 

A complex, fixed-point, decimal datum (packed or unpacked) 
of precision p is represented as a pair of real, fixed 
point, packed, decimal data of precision p. The first 
represents the real part of the complex value, and the 
second represents the imaginary part of the complex value. 

An unpacked, complex, decimal datum is aligned on a word 
boundary and occupies an integral number of bytes, some of 
which may be unused. 
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Complex Floating-Point Decimal (descriptor type 12) 

A complex- floating-point* decimal datum (packed or 
unpacked) of precision p is represented by a pair of real/ 
floating-point, packed, decimal data of precision p. The 
first represents the real part of the complex value and the 
last represents the imaginary part of the complex value. 

An unpacked, complex, decimal datum is aligned on a word 
boundary and occupies an integral number of bytes, some of 
which may be unused. 

Pointer (descriptor type 13) 

An unoac^ H pointer datum is represented by a ring number r, 

a segment number s, a word offset w, and a bit offset b, 

stored in a pair of 36-bit words the first of which has an 
even address. 

CHZ1 WHO w |0| b W/A 0 I 
023 17 30 3536 53 56 61 66 71 



A packed pointer datum is represented by a segment number s, 
a word offset w, and a bit offset b, stored as a string of 
36-bi ts. 



cm 

0 56 



w 



1718 



] 



35 



Offset (descriptor type lk) 

An offset datum (packed or unpacked) is represented by a 
word offset w, and a bit offset b, stored in a single 36-bit 
word . 



I w 1 o 1 fa Y//M 



1718202126 35 



Label (descriptor type 15) 

A label datum (packed or unpacked) is represented by a pair 

of unpacked pointers. The first pointer identifies a 

statement within a procedure and the second pointer 

identifies a stack frame of an activation of the block 

immediately containing the statement identified by the first 
poi nter . 
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Entry (descriptor type 16) 

An entry datum (packed or unpacked) is represented by a pair 
of unpacked pointers. The first pointer identifies an entry 
to a procedure and the second identifies a stack frame of an 
activation of the block immediately containing the procedure 
whose entry is identified by the first pointer. If the 
first pointer identifies an entry to an external procedure, 
the second pointer is null. 

Structure (descriptor type 17) 

A structure is an ordered sequence of scalar data. A packed 
structure contains only packed data, whereas an unpacked 
structure contains either packed or unpacked data or both. 
An unpacked structure contains at least one unpacked datum. 

A structure is aligned on a storage boundary that is the 
most stringent boundary required by any of its components. 
A packed structure that is not a member of a structure is 
aligned on a word boundary. 

An unpacked member of a structure is aligned on a word or 
double word boundary depending on its data type and occupies 
an integral number of words. 

A packed member of a structure is aligned on the first 
unused bit following the previous member, except that up to 
8 bits may be unused in order to insure that decimal 
arithmetic or non-varying string datum is aligned on a 9-bit 
byte boundary. 

An unpacked structure occupies an integral number of words. 

Area (descriptor type 18) 

An area datum (packed or unpacked) whose declared size is k 
occupies k words of storage, the first of which has an even 
address. The content of these k words is not yet defined as 
a Multics standard. 

Bit-String (descriptor type 19) 

A bit-string (packed or unpacked) whose length is n occupies 
n consecutive bits. The leftmost is bit 1 and the rightmost 
is bit n. An unpacked bit-string is aligned on a word 
boundary and occupies an integral number of words. Some 
bits of the last word may be unused. 
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Varying Bit-String (descriptor type 20) 

A varying bit-string (packed or unpacked) whose maximum 
length is n is represented by a real, fixed-point/ binary 
short, unaligned integer followed by a nonvarying bit-string 
of length n. 



m bi ts 




n bits 



The length of the current value is m. A varying bit-string 
is aligned on a word boundary and occupies an integral 
number of words, the last of which may contain unused bits. 

Character-String (descriptor type 21) 

A character-string (packed or unpacked) whose length is n 
occupies n consecutive 9-bit bytes. Each byte contains a 
single 7-bit ASCI! character right justified within the 
byte. The two unused bits must be zero. 

An unpacked character-string is aligned on a word boundary 
and occupies an integral number of words, the last of which 
may contain unused bytes. 



Varying Character-String (descriptor type 22) 



A varying character-string (packed or unpacked) whose 
maximum length is n is represented by a real, fixed-point, 
binary, short, unaligned integer followed by a nonvarying 
character-string of length n. 

m characters 



m 



n characters 



The length of the current value is m. 

A varying character-string is aligned on a word boundary and 
occupies an integral number of words the last of which may 
contain unused bytes. 
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File (descriptor type 23) 



A file datum (packed or unpacked) is represented by a pair 
of unpacked pointers the second of which points to a 
file-state block and the first of which points to a 
bit-string. Neither the form of the file-state block nor 
the form of the bit-string are defined as Multics standards. 

Arrays 



An array is an n-d imens ional , ordered collection of scalars 
or structures, all of which have identical attributes. The 
elements of an array are stored in row major order. (When 
accessed sequentially the rightmost subscript varies most 
rapidly). 



Summary of Data Descriptor Types 



1 real fixed-point binary short 

2 real fixed-point binary long 

3 real floating-point binary short 

5 complex fixed-point binary short 

6 complex fixed-point binary long 

7 complex floating-point binary short 

8 complex floating-point binary long 

9 real fixed-point decimal 

10 real floating-point decimal 

11 complex fixed-point decimal 

12 complex floating-point decimal 

13 pointer 
Ik offset 

15 label 

16 entry 

17 structure 

18 area 

19 bit-string 

20 varying bit-string 

21 character-string 

22 varying character-string 

23 file 



(c) Copyright/ 1972, Massachusetts Institute of Technology 

All rights reserved. (END)* 



MULT ICS PROGRAMMERS* MANUAL 



5.5 



Standard Data Formats and Codes 

8/10/72 



STANDARD SEGMENT FORMATS 

The Multics storage system does not make any restrictions or 
assumptions about the nature or format of the data stored in 
segments in the hierarchy. it does provide four length 
attributes for each segment giving some information about the 
contents: bit count, current length, maximum length, and number 
of records occupied. For a discussion of these and other 
attributes see the MPM Reference Guide section Segment, Directory 
and Link Attributes. 

The system commands and subroutines which deal with the 
contents of segments, however, expect them to be in one of a 
small number of formats: 

1) Object (procedure) segments for execution as machine 
instructions or as external -reference data (i.e., of the form 
alpha$beta), with special characteristics to satisfy the pure 
procedure and dynamic linking requirements of Multics. 

2) Archive segments for combining other segments (of any format) 
into a single segment, thus reducing the number of segments 
in a directory and eliminating the wasted bits at the end of 
the last record of each segment. 

3) ASCII character string segments for editing, printing, and as 
input to various Multics commands (e.g., the standard Multics 
language translators). 

h) Data segments peculiar to individual commands or subsystems. 
These have no standard format. 

Object Segments 

A Multics object segment contains an array of 
machine-executable and relocatable (to permit binding) words 
divided into four sections. 

1) The text section contains the pure executable part of the 
object program: instructions, read-only constants and 
relative pointers into the other sections. 

2) The definition section contains non-executable read-only 
symbolic information to be used in dynamic linking and 
symbolic debugging. 

3) The linkage section contains impure data: links which are 
snapped at execution time, and internal storage which exists 
beyond a single invocation of the program. 
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i*) The symbol section contains any pure data which does not 
belong in the other three sections. In particular, it 
contains a map of all other sections of the object segment 
and the symbol tree (a description of source language 
var i ables) . 

For a full description of object segments, see the MPM Reference 
Guide section Standard Object Segments. 

Archi ve Segments 

A segment in archive format consists of the individual 
component segments in linear juxtaposition, each component 
preceded by a header giving the name of the component, its length 
(in bits), and the time of creation of the component, as well as 
certain constant information used to verify that the segment is 
in fact correctly archived. All of the per-component header 
information is maintained as ASCII characters, so that if all the 
component segments are ASCII character string segments, the 
entire segment may be printed. Each component segment will be 
separated from the preceding one by a new page, since the first 
character in each header is the ASCII "new page" character. The 
name of the component will appear roughly in the center of the 
first line on the page, the actual contents beginning three lines 
1 ater . 

The terminal component of the name of an archive segment is 
".archive". Using the archive command, components may be added, 
deleted or replaced in an archive segment, and a table of the 
contents of the archive segment may be obtained. Archive 
segments are also used as input to the Multics binder (see the 
MPM Reference Guide section Standard Object Segments), the 
component segments of the archive being the object segments to be 
bound together. Note that archiving is similar to binding, but 
that an archive segment may not be properly executed as a 
procedure since no relocation is done on the data inside, and 
internal addressing references are thus incorrect. 

ASC I I Character String Segments 

Segments which are to be edited, printed, or used as input 
for standard translators and other commands are composed of 
strings of characters of the ASCII character set. Each 7-bit 
character is right justified in a 9-bit field, with the two 
high-order bits set to 0 and reserved for compatibility and 
future USASCII extensions. There are four characters per machine 
word, accessed sequentially from left to right, the first 
character of each word occupying the leftmost nine bits. The 
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segment's bit count is set by the creator of the segment to 
indicate 9 times the number of characters in the segment. 

ASCI I segments to be used as input to system commands 
frequently have very rigid format requirements. In these cases/ 
the command write-ups adequately describe the format. Language 
translator formats are usually described in a separate (non-MPM) 
document which is referenced in the write-up of the command which 
invokes the translator. The translators which require ASCII 
character string input segments are pll, fortran / aim, and basic. 
Other commands which require such input are bind/ 
enter__abs__reques t, exec_.com/ help, peruse_text/ runoff and 
set_search_rules . 

Many ASCII commands produce ASCII segments intended for 
printing. While these segments have a definite format/ that 
format is prepared by the command/ and the user need not know it 
in detail. These commands are the language translators, bind/ 
the absentee facility/ runoff and mail. 

Most of the ASCII input and output segments discussed above 
have reserved suffixes on their names. These suffixes are listed 
in the MPM Reference Guide section List of Names with Special 
Mean i ngs . 

Other 

The user may encounter some other segments which fit into 
none of the above categories. Some of these are: 

1) The breaks segment produced by the debug command to record 
information about breakpoints. 

2) The saved environment produced by the lisp and apl commands 
which may be reentered by a later invocation of lisp or apl. 

3) A message segment (with last component name .ms) which is an 
Administrative Ring segment and has its own managing 
subroutine. It is not accessible to the user. 

4) The user profile which is maintained by the abbrev and 
check_i nf o_segs commands. 
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V T*ATEQ1E$ £OR HANDLING UNUSUAL QCQURRENC5S 

During its execution/ a procedure may encounter a set of 
circumstances which prohibit it from continuing in the normal 
manner. Examples of such circumstances are an attempt to divide 
by zero and being unable to find a necessary segment in the 
storage system. Clearly, whether or not a particular set of 
circumstances, such as those given above, prohibits a procedure 
from continuing in a normal manner is dependent upon the 
procedure in question. Circumstances that are abnormal for one 
procedure may be quite normal when encountered in a different 
procedure. If it is unable to continue in the normal manner, a 
procedure will want to notify its caller or others of its 
ancestors that an unusual occurrence has taken place. This 
section, and the immediately following sections, describe means 
by which procedures can handle such occurrences and notify their 
ancestors of such occurrences. The means used to handle and send 
notification of unusual occurrences depends on many things, such 
as the significance of the effect of the occurrences, the 
expected frequency of the occurrences, the nature of the 
environment in which the program is executing, the nature of the 
occurrences, the ability to modify the circumstances, etc. 

The discussion of the methods of unusual occurrence 
reporting described below will enable users to understand how to 
handle unusual occurrences reported by system procedures^ Also, 
the discussion will enable users to better select an appropiate 
means for handling and reporting unusual occurrences that may 
arise during the execution of their own procedures. 

Printed Hessases 

The type of unusual occurrence reporting that most Multics 
users first encounter is a message printed on their terminals. 
Since, in some sense, the caller of a command is the user 
himself, printing a message on the user's terminal is the means 
by which a command can report an unusual occurrence to its 
caller. There are essentially two general types of printed 
messages used to report unusual occurrences: statements and 
questions. A statement is simply a description of the unusual 
occurrence that informs the user that the occurrence has been 
encountered. If the user wishes to take action to rectify the 
circumstances of the occurrence, he must subsequently issue 
commands to do so. A question gives a description of the 
occurrence, but also requests an immediate response from the user 
in the form of a character string entered at the terminal. In 
this way, the user must immediately specify one of several 
courses of action that the command will take with respect to the 
occurrence . 
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Most Multics system commands generate such printed messages 
in a standard format. For statements/ this format consists of 
the name of the command printing the statement, a description of 
the unusual occurrence causing the message to be printed, and 
more detailed information about the occurrence/ if appropriate. 
For questions, the format consists of the name of the command 
asking the question, followed by the question itself. The 
question contains sufficient descriptive information about the 
unusual occurrence so that the user can supply an intelligent 
reply. Two procedures, cornier r_ and command_query_ (see the MPM 
subroutine write-ups), are provided to help report unusual 
occurrences through printed statements and questions. Their use 
is strongly encouraged because they provide many facilities other 
than simple formatting. 

Status Codes 

For passing descriptions of unusual occurrences between 
procedures, the character string is too cumbersome and 
inefficient. For this purpose, a coded description of the 
unusual occurrence, called the status code, is used. The status 
code is either a short bit string or arithmetic number which 
takes on a different value for each possible unusual occurrence. 
If the status code is a bit string, usually each bit refers to 
the occurrence of some circumstance, as in Multics I/O system 
status. If the status code is an arithmetic number, then each 
different value corresponds to an unusual occurrence or set of 
unusual occurrences, as in the case of the Multics storage system 
codes. The status codes are passed from a calling procedure to 
the called procedure as an argument. The called procedure 
assigns the appropriate value to the argument at some point 
during its execution. When the called procedure returns to the 
calling procedure, the calling procedure examines the status code 
to determine what unusual occurrence has been encountered, if 
any, and then takes special action, if desired. Note that the 
status code is a means by which a called procedure may report an 
unusual occurrence only to its immediate ancestor. However, the 
first ancestor may, in turn, reflect the status code to its 
immediate ancestor/ and so on. 

Multics provides a means by which status codes may be 
generated and interpreted. The status codes generated by this 
facility are fixed binary(35) (one word) arithmetic numbers whose 
scope is a single process. The actual values of the codes are 
generated dynamically when referenced symbolically from a 
program, and may be interpreted (i.e., converted to a character 
string description) by calling com_err_, By using these 
dynamically generated status codes rather than status codes with 
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fixed, preassigned values, one avoids the problem of conflict 
between several separately compiled subsystems which may all use 
the same status code to represent different occurrences. In the 
dynamic scheme, all status codes are guaranteed to be unique 

within a process. Note that status codes cannot be used in a 
process other than the one generating them because they will not 
have the same interpretation in another process. 

In order to have a status code generated, a Multics standard 
status code segment must exist. (A description of how to 
generate a standard status code segment is given in the MPM 
Subsystem Writers 1 Supplement (SWS).) This segment contains an 
externally defined symbol corresponding to each status code to be 
generated in the segment, as well as space for the code itself, 
and the character string interpretation of the code. When the 
status code segment is first referenced in a process, the system 
generates a new value for each status code defined in the 
segment, and stores it into the segment. (Actually, it is stored 
into the linkage section of the status code segment, so that a 
different status code may be generated for each process.) From 
then on, all references to that external symbol will be 
referencing the generated status code. com_err_ / when given such 
a status code, is able to locate and return the associated 
character string interpretation. 

When a program wishes to reference a status code, it must do 
so symbolically. If, for example, a program wished to return a 
status code appearing in the status code segment "mistake" and 
having the external symbol "bad_argumen t", then the following 
PL/ I statements would be needed: 

declare mi s take$bad_argumen t fixed bin(35) external; 
return (mi stake$bad_argument ) ; 

If a program wanted to examine a status code for a particular 
value to determine if it should take some distinct action, it 
would contain statements like: 

declare mi s take$bad_argumen t fixed bin(3i>) external; 

if status_code = mi s take$bad__a rgumen t then do; 

Note that all references to the status code are symbolic and that 
the mechanism of generating the status code is automatic and not 
visible to the program or programmer at all. 
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Most Multics system procedures use standard status codes. A 
list containing the symbolic names, character string 
interpretations, and meaning of the status codes returned by 
system procedures is given in the MPM Reference Guide section. 
List of System Status Codes and Meanings. 

Important Note 

Some of the documents describing MPM subroutines declare 
their status code argument (usually called "code") as fixed bin 
or fixed bin(17). This is a vestige of an earlier form of status 
codes. Users should declare all status codes returned by MPM 
subroutines as fixed bin(35), although any of the three 
declarations will generally work correctly. 

Cond i t i ons 

Status codes enable an ancestor procedure to take action on 
an unusual occurrence only after the procedure encountering the 
occurrence has returned. It is sometimes necessary for an 
ancestor procedure to gain control immediately upon encountering 
an unusual occurrence, so that it may decide what action to take. 
If the ancestor procedure decides to take corrective action, it 
may then continue execution from the point of the occurrence. 
This is the purpose of the Multics condition mechanism as 
described, in detail, in the MPM Reference Guide section, The 
Multics Condition Mechanism. 

The Multics system invokes the condition mechanism upon 
encountering certain unusual occurrences during the execution of 
a process. The Multics standard user enviroment acts upon these 
system generated occurrences, as well as user program generated 
occurrences, if the user programs do not do so themselves. A 
list of occurrences which cause the system to invoke the 
condition mechanism, and the action taken by the Multics standard 
user environment if it is invoked to act upon these occurrences, 
is given in the MPM Reference Guide section, List of System 
Conditions and Default Handlers. 

faults. 

There is a class of unusual occurrences that are detected by 
the Multics hardware processor. These occurrences are called 
fajjjjts_, and are a subset of the set of occurrences that cause the 
system to invoke the condition mechanism. They are, therefore, 
included in the List of System Conditions and Default Handlers in 
the MPM Reference Guide. 
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THE MULTICS CONDITION MECHANISM 

The condition mechanism is a facility of the Multics system 
that notifies a program of an exceptional condition detected 
during its execution- A cond 1 1 i on is a state of the executing 
process. Each condition that is detected is i dent i f i ed .by a 
condition name . For example, division by zero is a condition 
identified by the condition name, zerodivide. An attempt by a 
user to exceed his storage allocation limit is a condition 
identified by the name, record_quota_overf low. 

A condition can be detected by the system or by a user 
program. When a condition is detected, it is si gnal 1 ed . A 
signal causes a block activation of the most recently established 
on unit for the condition. Thus, by establishing an on unit, a 
program arranges with the system to receive control when 
conditions of interest to it are detected and signalled. 

An on uni t can be a begin block or independent statement, or 
it can be a procedure entry. A program (an activation of a 
procedure block or begin block) can establ i sh a begin block or an 
independent statement as an on unit for a particular condition by 
executing an PL/I on statement that names that condition. A 
program can establish a procedure entry as an on unit by calling 
the condition., subroutine with the condition name as an argument. 
(See the MPM subroutine write-up.) 

When an on unit is activated, it can take any action to 
handle a condition. Typically, the on unit might try to rectify 
the circumstances that caused the condition and then restart 
execution of the interrupted program at the point where the 
condition was detected; or it might abort execution of the 
program by performing a nonlocal transfer to a location within 
the interrupted program or to one of its callers. 

All of the on units established by a block activation are 
reverted when that block activation terminates by returning to 
its caller or when it is aborted by a nonlocal transfer. An on 
unit for a particular condition can be explicitly reverted. If 
the on unit is a begin block or an independent statement, it can 
be reverted by executing a PL/ I revert statement, or by executing 
another on statement, naming the condition. If it is a procedure 
entry, it can be reverted by calling the reversion^ subroutine, 
or by calling the condition., subroutine again, with the condition 
name as an argument. (See the MPM subroutine write-up for 
reversion,.. ) Therefore, each block activation can have no more 
than one on unit established for each condition at any given 
time; however, there can be as many on units established for a 
particular condition as there are block activations. Signalling 
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a condition causes a block activation of the most recently 
established on unit for that condition. Normally/ this is the 
only on unit that is activated/ even though other on units for 
the condition were established by preceding block activations. 

The effect of this scheme is that/ once a block activation 
has established an on unit for a condition/ any occurrence of the 
condition activates that on unit. This remains true only until 
the block activation is terminated or until the on unit is 
reverted and while no descendant block activation establishes an 
on unit for the condition. 

The general philosophy of establishing on units is that 
procedures that can take action when a condition is detected 
should establish an on unit for that condition. Of those block 
activations that have established an on unit for the condition/ 
the most recently established on unit is activated since the most 
recent is probably the best qualified to handle the condition. 

The conditions detected and signalled by the system are 
listed in the MPM Reference Guide section/ List of System 
Conditions and Default On Unit Actions. Methods of signalling 
conditions from user programs are discussed later in this 
wr i te-up. 

An Exampl e of the Condi tion Mechani sm 

The example below is presented to illustrate the mechanism 
discussed above. it is not meant to illustrate typical or 
recommended use of the condition mechanism. 

Example: proc; 

declare Subl external entry; 
declare Sub2 external entry; 
declare c fixed bin; 
declare wrong_way condition; 

on wrong_ way begin; (1) 



end; 

call Subl; (2) 
c = 2; (3) 
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call Sub2; 
end Example; 



Subl: proc; 

declare a fixed bin; 
declare wrong_way condition; 

a = 0; 

on wrong_way begin; 



(SI) 
(S2) 



end; 
a - 1; 
end Subl; 



(S3) 



Sub2: proc; 

declare b fixed bin; 
declare wrong_way condition; 

b = 1; 

on wrong_way begin; 



(Si*) 
(S5) 



end; 
b = 2; 

revert wrong_way; 
b = 3; 
end Sub2; 



(S6) 
(S7) 
(S8) 



In the above example, if procedure Example is called, the 
executable statements are executed in the order, (1), (2), (SI), 
(S2), (S3), (3), (I*), (SU), (S5), (S6), (S7), (S8), under normal 
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circumstances. However, if the wrong_way condition is detected 
and signalled during the execution of (SI)/ then the on unit 
established for wrong_way by Example is activated because Subl 
has not established an on unit for the wrong_way condition at 
this time. If the on unit simply corrects the circumstances that 
caused the wrongjway condition and returns, then execution 
resumes in (SI) from the point of interruption. If condition 
wrong__way is detected and signalled during the execution of 
statement (S3), then the on unit estalished in Subl is activated 
because Subl has established the most recent on unit for 
wrongjway. If wrong_way is signalled during (3), the on unit 
established by Example is activated because the block activation 
for Subl has been terminated and its on unit is no longer 
established. If wrong_way is signalled during (S8), the on unit 
established in Example is activated because Sub2 explicitly 
reverted the on unit it had previously established, making 
Example's on unit the most recently estalished wrong_way on unit. 

An On Uni t Act i vated by Al 1 Condi tions 

The above description inidcates how on units can be 
established for specific conditions. It is sometimes desirable 
to handle any and all conditions that occur. To do this, a block 
activation can establish an on unit for the any_pther condition. 
When a particular condition is signalled, the any_pther on unit 
established by the block activation is activated if no specific 
on unit for the condition was established by the block 
activation, and if no on unit for that condition or the any_pther 
condition was established by a more recent block activation. In 
other words, when a condition is signalled, each block 

activation* starting with the most recent* is inspected for an on 
unit established for that specific condition and, if none is 
found, for an established any_other on unit. The first such 
specific or any_other on unit found is the one that is activated. 
Note that, as with on units for specific conditions, only one 
any_other on unit can be established by a given block activation. 
Establishing a second any__other on unit simply overwrites the 
first. 

As a summary, the flow diagram of Figure 1 illustrates the 
algorithm used by the condition mechanism to determine which on 
unit to activate when a condition is signalled. The action taken 
when no on unit for a condition can be found is described later 
in this write-up. 
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Obtai ni ng Addi t ional 1 nformation About a Condi tion 

An on unit might (in fact,, probably does) need information 
about the circumstances under which it was activated. The 
f i nd_condi t ion_i nfo__ subroutine (described in an MPM subroutine 
write-up) makes such information available to an on unit. The 
information might include machine conditions (i.e., the processor 
state) or other information describing the condition in question. 
The information that is avai lable when system-detected conditions 
are signalled is listed in the MPM Reference Guide section, List 
of System Conditions and Default On Unit Actions. 

i nteract i on wi th the Mul t i cs R i ng Structure 

The condition mechanism interacts with the Multics ring 
structure. The above description of how an on unit is selected 
for activation applies only to block activations within a single 
ring. When a condition is signalled in a particular ring, the 
algorithm of Figure 1 is followed for the block activations in 
that ring. If no on unit for the condition is found in that 
ring, then the ring is abandoned and the same condition is 
signalled in the higher ring that called the abandoned ring. 
This process is repeated until all existing rings have been 
abandoned, indicating that this process has not established an on 
unit for the condition being signalled, in which case the process 
is terminated. 

Si gnal 1 i ng Condi t ions i n a. User Program 

A user program can signal a condition by executing a PL/ I 
signal statement that names that condition. Alternately, it can 
call the signals subroutine with the condition name as an 
argument. (See the MPM subroutine write-up for signal^.) If the 
on unit activated by the signal returns, the user program should 
retry the operation that was interrupted by the condition. 

Pi f f erences Between PL/ I and Mu 1 1 i cs Condi tion Mechani sms 

The PL/I language on, revert, and signal statements are very 
similar in purpose and function to the Multics condition^, 
reversion^., and signal_ subroutines and for many applications can 
be used interchangeably. However, there are important 
differences between them as noted below, and the user should not 
interchange them blindly. The signal_ subroutine can be called 
with arguments that describe the particular circumstances under 
which a condition is being signalled. (See the MPM subroutine 
write-up for signal_. ) The PL/I signal statement does not accept 
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arguments. Therefore, a block activation must call signals if it 
wants to pass descriptive arguments when signalling a condition. 

Executing a PL/I on statement to establish an on unit is 
equivalent to calling the condition., subroutine. An on unit 
established for a condition by either method is activated when 
the condition is signalled, either by the execution of a PL/I 
signal statement or by a call to the signal_ subroutine. 
However, an on unit established by calling condition., must be a 
procedure entry; therefore, it can accept the descriptive 
arguments passed with the signal by signal_. An on unit 
established by executing a PL/I on statement must be a begin 
block or an independent statement; it can refer to the arguments 
passed by signal_ only by calling the f ? nd_condi t i on_i nf o_ 
subrout i ne. 

A PL/ 1 on statement and a call to the condition., subroutine 
must not be executed by the same block activation in order to 
establish an on unit for a given condition. Also, a PL/ I revert 
statement can only revert on units established by an on 
statement, but cannot revert on units established by condition... 
Similarly, the reversion^ subroutine can only revert on units 
established by condition., but cannot revert on units established 
by an on statement. 

In PL/I Version 2, when calls to condition_or reversion.. 

appear within the scope of an internal procedure, the 

no_qu i ck_b locks option must be specified in the procedure 

statement of that procedure. The no_qu i ck_bl ocks option is a 

nonstandard feature of the Multics PL/I language; therefore, 

programs using it might require conversion when being transferred 
to other systems. 

Act i on Taken fry the Def aul t On Uni t 

Some conditions are routinely handled by the system's 
default on unit (in the absence of a user-supplied on unit) by 
printing a message on the user's terminal to alert him that the 
condition has occurred and returning to command level. These 
conditions are denoted by "Default action: prints a message and 
returns to command level." in the MPM Reference Guide section, 
List of System Conditions and Default On Unit Actions. 

In many cases, the subroutine that is executing when a 
condition is detected is a system or PL/I support subroutine that 
is of little interest to the user. In such cases, the user needs 
to know the location at that the most recent non-support 
subroutine was executing before the condition was detected. To 
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fill this need, the default on unit actually hunts through the 
block activations that precede the support subroutine until it 
finds the first non-support subroutine; it then indicates that 
the condition was detected while executing at a location within 
that non-support subroutine. 

Machi ne Condi t ions 

As described above, information is available that describes 
the state of the processor at the time a hardware condition 
(fault) was raised. It has the following declaration: 

declare 1 mc based (mc_ptr) aligned, 
2 prs (0:7) ptr, 
(2 regs, 

3 x (0:7) bit(18), 

3 a bit(36), 

3 q bit(36), 

3 e bit(8), 

3 pad bit(6i*) / 
2 scu (0:7) bit(36), 
2 padl bit(108), 
2 errcode fixed bin(35), 
2 pad2 bit(7 2), 
2 ring bit(18), 
2 fault_time bit(5*0, 
2 pad3 (0:7) bit(36) ) unaligned; 



1) prs is the contents of the 8 pointer registers at the 

time the condition occurred. 

2) regs is the contents of the other registers at the time 

the condition occurred. 

a) x is the contents of the 8 index registers. 

b) a is the accumulator contents. 

c) q is the q-register contents. 

d) e is the exponent register contents. 

3) scu is the stored control unit, expanded below. 



h) errcode is the fault error code. Refer to the MPM 

Reference Guide section, List of Sysyem Status 
Codes and Meanings. 
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5) ring is the ring in which the condition occurred. 

6) fau1t_time is the time the condition occurred. 

The stored control unit is declared as follows: 

declare 1 scu aligned/ 

/* WORD (0) */ 

(2 ppr, 

3 prr bit(3) / 
3 psr bit(15), 
3 p bit(l), 
2 padU bit(17), 

/* WORD (1) */ 

2 pad5 bit(35) / 
2 fi_flag bit(l), 

/* WORD (2) */ 

2 tpr, 

3 trr bit(3), 
3 tsr bit(15), 

2 pad6 ibt(18), 

/* WORD (3) */ 

2 pad7 bit(30), 
2 tpr_tbr bit(6), 

/* WORD U) */ 

2 ilc bit(18) / 

2 ir, 

3 zero bi t( 1), 
3 neg bi til), 

3 carry bi t( 1), 

3 ovfl bit(l), 

3 eovf bit(l), 

3 eufl bit(l), 

3 oflm bit(l), 

3 tro bit(l), 

3 par bit(l), 

3 parm bit(l), 

3 bm bi t( I), 



© Copyright, 1973, Massachusetts 

and Honeywel 1 



institute of Technology 
information Systems inc. 



MULT ICS PROGRAMMERS' MANUAL 



6.2 



Condition Mechanism 
Handling Unusual Occurrances 

Page 9 
10/18/73 



1) PPr 

a) prr 

b) psr 

c) p 

2) f i_flag 

3) tpr 

a) trr 

b) tsr 
h) tpr_tbr 

5) ilc 

6) ir 

a) zero 

b) neg 

c) carry 



3 tru bit(l), 
3 mif bit(l), 
3 3 k s b?t(l) 
3 pad bit(U)^ 

/* WORD (5) */ 

2 ca bit(18>, 
2 pad8 bit(18), 

/* WORD (6) */ 

2 even_inst bit<36), 

/* WORD (7) */ 

2 odd_inst bit(36); 

is the procedure pointer register contents, 
is the ring number portion of ppr. 

is the segment number portion of ppr. 
is the procedure privileged bit. 



equals "l"b after a fault, lf 0"b 
i nterrupt . 



after 



an 



is the temporary pointer register contents. 

is the ring number portion of ptr. 

is the segment number portion of tpr. 

is the bit offset portion of tpr. 

is the instruction counter contents. 

is the contents of indicator registers. 

zero indicator. 

negative indicator. 

carry indicator. 
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d) ovfl 

e) eovf 

f) eufl 

g) oflm 

h) tro 

i ) par 

j ) pa rm 
k) bm 
1 ) tru 
m) mi f 
n) abs 

7) ca 

8) even_Jnst 

9) odd inst 



overflow indicator. 

exponent overflow. 

exponent underflow. 

overflow mask. 

tally runout. 

pari ty error. 

pari ty mask. 

bar mode. 

truncation mode. 

multiword instruction mode. 

absolute mode. 

is the computed address. 

the instruction causing the fault is stored here. 

the next sequential instruction is stored here if 
ilc (see above) is even. 



1 nformat ion Header Format 

A standard header is required at the beginning of each 
information structure provided to an on unit. This information 
is particular to the condition in question and varies among 
conditions except for the header. The format of that header is: 

declare 1 i nfo_ structure aligned, 

2 length fixed bin, 

2 version fixed bin, 

2 action_flags aligned, 

3 cant__res tar t bit(l) unaligned, 
3 def aul t_ restart bit(l) unaligned, 
3 pad bit(34) unaligned, 

2 info_string char(256) var, 

2 s tatus_code fixed b i n( 35 ) , 



1) length 



is the length of the structure in words. 
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2) version is the version number of this structure. 

3) act i on__f 1 ags indicates appropriate behavior for a handler: 

cant_restart if "l ,, b / a handler should never attempt to 

return to the signalling procedure. 

def aul t_restart if "l"b, the computation can resume with no 

further action on the handler's part except a 
return. 



k) info_string 
5) status_code 



is a printabel message about the condition. 

if nonzero, is a code i nterpretabl e by 
com_err_ further defining the condition. 



If neither action flag is set / restarting is possible, but 
its success depends on action taken by the handler. 
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Condition x Raised 



Examine 
most recent 
activation 



Examine next 
previous 
activation 



C 



c 



No 



Is there so. on unit established 
this activation for condit 



hed in *\ 
ion x? y 



Yes 



No 



Is there an any_other on unit ^ 
established in this activation? / 



Yes 



r 



Invoke the 
on unit 



No 



Is this the oldest 
activation? 



1 


Yes 

■ 


No oh unit for 
this condition 



Figure 1: Simplified algorithm for determining which 
on unit to invoke when condition x is raised. 
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NONLOCAL TRANSFERS AND CLEANUP PROCEDURES 

Many languages provide the ability to perform nonlocal 
transfers. In Multics, this is a facility by which the currently 
executing procedure activation may transfer to a location in an 
earlier existing procedure activation and, as a consequence, 
abort all activations descendant from the earlier activation. 
Programmers of certain types of procedures may wish to have these 
procedures establish a set of code to be executed if an 
activation of one or more of these procedures is aborted in this 
manner. An example of such a procedure is a program that 
references static data that must be reset so that the procedure 
can be reentered. This function of executing predefined code 
when an activation is aborted by a nonlocal transfer is termed 
cl ean i ng up . A procedure or entry that contains the code for 
cleaning up is termed a cleanup procedure . 

A procedure may establish a cleanup procedure by calling the 
MPM subroutine establ i sh_cl eanup_proc_. Having a cleanup 
procedure established will cause the specified cleanup procedure 
to be invoked if the establishing block activation is aborted by 
a nonlocal transfer. The establishment of a cleanup procedure 
may be reverted by calling the MPM subroutine 
revert_cl eanup_proc_. If a procedure activation is terminated 
either normally by a return or abnormally by a nonlocal transfer, 
any established cleanup procedure is automatically reverted. In 
the latter case of an abnormal termination, the cleanup procedure 
is automatically reverted when it is invoked. 

In PL/I Version 2, when calls to establ i sh_cl eanup_proc_ or 
revert_cl eanup_proc_ appear within the scope of a begin block or 
internal procedure of a procedure, the no_qu ick_blocks option 
must be specified in the procedure statement of that procedure. 
The no__quick_b locks option is a nonstandard feature of the 
Multics PL/ I language and, therefore, programs using it may not 
be transferable to other systems. 
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LIST OF SYSTEM STATUS CODES AND MEANINGS 

Status codes report unusual occurences encountered by 
procedures during execution. The codes are returned by Multics 
System commands and subroutines. Printed messages which 
correspond to these status codes appear on printed output in the 
format consisting of the name of the command printing the 
statement, a description of the unusual occurrence causing the 
message to be printed, and more detailed information when 
appropriate. 

To test for the return of a particular system-defined status 
code, the following approach can be taken in order to avoid 
compiling particular numeric values, which might change, into 
programs : 

declare er ror_tabl e__$ent ry 

if code = error_tabl e_$entry then ... 

where 

1) code is a status code (fixed binary(35)) returned from 

a Multics system command or subroutine. 

2) entry is an error_table_ entry taken from the list 

below. 

See also the MPM Reference Guide section, Strategies for 
Handling Unusual Occurences, and the subroutine write-up for 
com_err_. com_err_ reflects to printed output the occurrence and 
interpretation of any of the status codes. 

The first part of this write-up contains an alphabetic list 
of printed messages. Each message is followed by the name of the 
entry for the status code in error_tabl e_. The er ror_tabl e_ 
entry name is followed by a more extensive interpretation of the 
status code. 

This version of er ror__tabl e_ is accurate through Multics 
system 20.12 
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A call that must be in a sequence of calls was out of sequence. 
(error_ tab 1 e__$out_o frequence) 

Meaning: The procedure called required another call to have 
been made prior to this call. 
A logical error has occurred in initial connection. 
(error_tabl e__$net_i cp_error ) 

Meaning: Network only. A Network connection management 
program has detected an error in the execution of Network 
protocol to establish a connection to a foreign host. 
Re-try the connection attempt; if the problem persists, it 
may be a sign that either the foreign host or Multics is not 
properly following Network protocol. 
ACL/CACL is empty. 

(error_table__$empty_acl ) 

Meaning: The ACL of a directory or segment is empty. 
Allocation could not be performed. 
(error_tabl e__$notal loc) 

Meaning: This operation required an allocation in an area 
that did not contain enough space to perform the allocation. 
An event channel is being used in an incorrect ring. 
(error_tabl e_$wrong_channel__r i ng) 

Meaning: A channel name was supplied that does not 
correspond to a channel in the current ring. 
An initial connection is already in progress from this socket, 
(er ror_tabl e_$net_a 1 ready_i cp) 

Meaning: Network only. The user's process has requested 
that a Network connection be established from a local socket 
that is already involved in a connection attempt. If 
possible, the user should direct his program to use a 
different socket, or, if appropriate, close the 
already-established connection if it is no longer desired. 
Append permission missing. 

(er ror_table__$no__append) 

Meaning: Append permission is missing for an operation that 
requires it. 
Argument ignored. 

(er ror__tab1 e__$arg_i gnored ) 

Meaning: An argument was found that was not expected and 
was ignored. 
Argument is not an ITS pointer. 
(error_tab1 e_$bad_ptr ) 

Meaning: One of the argument pointers, in the argument list 
used in a cross-ring call, is not in the correct format. 
Argument size too small. 

(error_tabl e_$smal larg) 

Meaning: The argument size is too small (in length). 
Argument too long. 

(er ror_tabl e_$b i garg) 
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Meaning: An entry name argument greater than 32 characters 
or a path name argument greater than 168 characters was 
passed to a program. 
Attachment loop. 

(error_tabl e_$att_Joop) 

Meaning: The attempted attachment would result in the given 
stream being attached to itself, either directly or 
indirectly, through intermediate outer modules. 
Attempt to access beyond end of segment. 
(error_tabl e_$boundv iol ) 

Meaning: An attempt was made to access beyond the maximum 
length of the segment. 
Attempt to attach to an invalid device. 
(error_table_$ i nval id_device) 

Meaning: The device specified in this I/O system attach 
call is not of a type handled by the I OS I M to which the 
attach was directed. 
Attempt to change first pointer, 
(er ror_tabl e_$change_f i rst) 

Meaning: The type of device associated with the given 
stream name does not permit the value of the first reference 
pointer to be changed. 
Attempt to convert directory or link to multisegment file, 
(er ror_tabl e_$bad_ms_conve rt ) 

Meaning: An unsuccessful attempt was made to convert a 
directory or link to a multisegment file. 
Attempt to delete segment whose safety switch is on. 
(error_tabl e__$saf ety__sw_on ) 

Meaning: The user attempted to delete a segment, directory, 
or directory subtree for which the safety switch was on 
(preventing deletions). 
Attempt to execute in data segment. 
(error__tabl e_$execute_data ) 

Meaning: The user has attempted to transfer to a segment to 

which he does not have execute access. 
Attempt to manipulate last or bound pointers for device that was 
not attached as writeable. 

(error_tabl e_$ inval id_seek__last_bound) 

Meaning: Changing the position of the last or bound 

reference pointers of a device that cannot be written is 

nonsensical and is therefore not allowed. 
Attempt to read or move read pointer on device which was not 
attached as readable. 

(error_tabl e_$ i nval i d_read) 

Meaning: Changing the position of the read reference 
pointer of a device that cannot be read is nonsensical and 
is therefore not allowed. From tape_: an attempt was made 
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to change the mode from write to read during a seek request. 
Attempt to set delimiters for device while element size is too 
large to support search. 

(er ror_tabl e_$ i nval i d_setde1 im) 

Meaning: The type of device associated with the given 
stream does not support read delimiters or break characters 
with the current element size. 

Attempt to set max length of a segment less than its current 

length. 

(error_table_$ i nval id_max_l ength) 

Meaning: The user attempted to set the maximum length of a 
segment to a value less than its current length. 
Attempt to specify the same segment as both old and new. 
(error_tabl e_$sameseg) 

Meaning: There was an attempt to use a single segment 
(possibly specified twice) with an operation that requires 
two different segments (e.g., copying). 
Attempt to unlock a lock that was not locked. 
( e r ro r_t a b 1 e_$ 1 oc k__no t_J oc ked ) 

Meaning: An attempt was made to unlock a lock that was not 
1 ocked . 

Attempt to unlock a lock which was locked by another process, 
(er ror_tabl e_$ 1 ocked_by_o the reprocess ) 

Meaning: An attempt was made to unlock a lock that was 

locked by another existing process. 
Attempt to write or move write pointer on device which was not 
attached as writeable. 

(error_table_$ inval id__wr i te) 

Meaning: Changing the position of the write reference 
pointer of a device that cannot be written is nonsensical 
and is therefore not allowed. From tape_: an attempt was 
made to change the mode from read to write during a seek 
request . 
Bad class code in definition. 

( e r ro r_t a b 1 e_$ ba d__c 1 a s s_def ) 

Meaning: An object segment containing nonstandard 
information was referenced. 
Bad definitions pointer in linkage. 
(error_tabl e__$no_def s ) 

Meaning: The linkage section has been illegally modified. 
Bad gate for entry referenced. 

(error_tabl e__$bad__arg_type) 

Meaning: A bad argument specification was found in the gate 
validation information. 
Bad mode specification for ACL/CACL. 
(error_tabl e_$bad_acl_mode) 

Meaning: The user specified an illegal mode or combination 
of modes in the process of setting an ACL. 
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Bad socket gender involved in this request. 
(error__tabl e_$net_bad_gender ) 

Meaning: Network only, A Network socket connection is 
either read-only or write-only; an attempt has been made to 
perform the opposite operation on a socket. 
Bad syntax in pathname. 

(error_tabl e_$badpath ) 

Meaning: A syntax error of the following form was used in a 
path name: 1) a less than character (<) following a 
non-less than character (e.g./ <a< or <><); 2) two 
sucessive greater than characters (e.g., >>); or 3) a 
greater than character immediately following a less than 
character (e.g., <>). 
Brackets do not balance. 

(error_tabl e__$unba 1 anced_b rackets ) 

Meaning: The brackets in a command line do not balance. 
Communications with this foreign host not enabled. 
(error_tabl e_$net__f host_i nact i ve) 

Meaning: Network only. The user has requested a connection 
to a foreign Network host with whom Multics does not 
routinely communicate. If communication with this host is 
desired/ the user should consult the local installation 
management or Network technical 1 iason. 
Connection not completed within specified time interval. 
(error_tabl e__$net__t imeout ) 

Meaning: Network only. The user's process has attempted to 
establish a Network connection to a foreign host, but that 
host has not responded within a reasonable period of time. 
Most likely, the foreign host is overloaded/ or is about to 
cease all Network communication for some reason. 
Could not create dartmouth job core. 
(error__tabl e_$no _job__core) 

Meaning: The Dartmouth subsystem encountered a system error 
while attempting to create temporary segments in the process 
di rectory. 

Current processid does not match stored value, 
(er ror_tabl e_$bad_process i d ) 

Meanings: The user has tried to use a socket that belongs 
to some other process. 
Dartmouth job aborted. 

(er ror_tabl e_$dart_abort ) 

Meaning: The Dartmouth subsystem cound not find a Dartmouth 
command (e.g., basic) in the library; or the Dartmouth 
subsystem encountered a system error while attempting to 
creat temporary segments in the process directory. 
Data not in expected format. 

(e r ror_tab 1 e_$ i mprope r_da ta_f o rma t ) 
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Meaning: From tape_: the tape to be read is not in Multics 
standard tape format. 
Directory or link found in multisegment file, 
(er ror_table_$bad_ms_f i 1 e) 

Meaning: A directory or link was found in a multisegment 
file. Only segments are permitted as components of a 
multisegment file. 
Directory pathname too long, 
(er ror_table_$di rlong) 

Meaning: A specified directory name is greater than 168 
characters in length. 
Duplicate entry name in bound segment. 
( e r ro r_t a b 1 e_ $ dup_e n t_name ) 

Meaning: Two or more components containing entry points 
with the same name were bound together, and the user 
referred to bound_seg_name$ent ry_name so that the 
appropriate entry point cannot be determined. 
Entry is not a branch. 

(error__tabl e — $ no t__a__b ranch ) 

Meaning: A storage system entry that is not a branch was 
used in a context where a branch was expected. 
Entry is not a directory. 

(error_tabl e_$notad i r ) 

Meaning: A storage system entry that is not a directory was 
used in a context where a directory was expected. 
Entry name too long. 

(er ror_tabl e__$ent 1 ong) 

Meaning: The specified entry name in a directory is greater 
than 32 characters in length (perhaps after the addition of 
a suffix component/ e.g.; .pll, .archive/ etc.). 
Entry not found. 

(er ror_tabl e_$noentry) 

Meaning: The branch specified by the path name does not 
ex i s t . 

Equals convention makes entry name too long, 
(er ror — tabl e_$ longeql ) 

Meaning: The user supplied a name with the equals 
convention which/ when expanded/ becomes greater than 32 
characters in length. 
Error in internal ioat information. 
( e r r o r_t a b 1 e_$ i oa t__e r r ) 

Meaning: System error. Contact Multics operations. 
Error zeroing entry in the linkage offset table. 
(error_tabl e_$ loterr ) 

Meaning: The linkage section is in an improper format. 
Expanded command line is too large. 

(er ror_table_$command_J i ne_overf low) 

Meaning: The evaluation of active functions has overflowed 
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the available space for command line expansion. See the 
command set_com_l i ne . 
Expected argument descriptor missing. 
(error_table_$nodescr ) 

Meaning: The expected argument descriptor is missing. 
Expected argument missing, 
(er ror_tabl e_$noarg) 

Meaning: An argument expected by a program was not passed 
to that program. 
External symbol not found. 

(er ror_tabl e_$no_ext_sym) 

Meaning: The entry name was not found on the segment being 
referenced . 
Fatal error. Translation aborted. 

(er ror_tabl e_$ trans 1 at ion_aborted ) 

Meaning: The translator has become internally inconsistent/ 
probably not due to the source program, and is reverting 
directly to command level. 
Foreign IMP is down. 

(er ror_tabl e_$net_f imp_down) 

Meaning: Network only. The user has attempted to connect 
to, or has had an open connection to a network host whose 
Interface Message Processor has gone down. Communication 
with that host is not possible at this time. 
Foreign host is down. 

(er ror_tabl e_$net_f host__ down) 

Meaning: Network only. The user has attempted to connect 
to a Network host which is not presently communicating with 
the Network, or has had an open Network connection to a 
foreign host that has just ceased communicating with the 
Network. 

10 device failed to become unassigned. 
(error_table_$io_st i 1 l__assnd) 

Meaning: A call to detach an I/O device failed for some 
reason. From tape_: a different reel ID was specified on 
detaching the stream than on attaching it. 
10 device not currently assigned. 
( e r r o r_t a b 1 e_$ de v__n t_a s s nd ) 

Meaning: A call was made to perform I/O using an illegal 
device. 
I 1 legal entry name. 

(er ror__tabl e__$badstar ) 

Meaning: A syntax error of the following form appeared in 
an entry name utilizing the star convention: 1) a null 
component; 2) a less than (<) or greater than (>) 
character; 3) a non-printing ASCII character (e.g./ tab or 
new line); h) more than one component of n ** n ; or 5) a 
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component which is not "**" but contains more than one * 
character. 

Illegal entry point name in make_ptr call. 
( e r r o r__ t a b 1 e_$ ba d_e n t r y_po i n t_name ) 

Meaning: There is an illegal entry point name in the 
hcs_ $make_pt r call. 
Illegal host number or id. 

(er ror__tabl e_$net_bad_hos t ) 

Meaning: Network only. The user has specified a Network 
host name unknown to Multics, or has given a host number 
which was either negative or greater than the largest host 
number known to Multics. The user should check the spelling 
of the name or number. 
Illegal initialization info passed with create- i f -not-found link. 
(error_tabl e_$bad_l i nk_target_i ni t_info) 

Meaning: There is an unrecognizable action code in the 
initialization information for a link target to be created 
when first linked to. 
Illegal self reference type. 

(error_table_$bad_sel f_ref ) 

Meaning: The object segment is in an invalid format. 
Illegal type code in type pair block. 

(er ror_tabl e_$bad__l ink__type) 

Meaning: The object segment is in an invalid format. 
Illegal use of equals convention, 
(er ror_tabl e_$badequal ) 

Meaning: There was no letter or component in the entry name 
that corresponds to a % or an = in the equal name. 
Improper access to given argument, 
(er ror_tabl e_$bad_arg_acc) 

Meaning: An argument to which the process does not have 
access was passed on a cross-ring call. 
Improper mode specification for this device, 
(er ror_tabl e_$bad__mode ) 

Meaning: Either the given I/O mode specification was of 
illegal syntax or the type of device associated with the 
given stream does not support one or more of the modes. 
From tape_: The mode specification on the attach call was 
other than r or w. 
Improper syntax in command name. 

(error_table_$bad_command_name) 

Meaning: Command name is of the form a$, $a, or $. 
Inconsistent combination of control arguments, 
(er ror_table_$ i neons i stent ) 

Meaning: The command invocation contained an i neons i stent 
combination of control arguments. 
Incorrect access on entry, 
(er ror_tabl e_$moder r ) 
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Meaning: The user attempted to reference a segment to which 
he has insufficient access for the reference, but has 
sufficient access to know of its existence. 
Incorrect access to directory containing entry. 
(error_table_$ i ncorrect_access ) 

Meaning: The user had incorrect access to the directory 
containing the entry he wished to access; i.e., the access 
mode required for the operation was not present. 
Incorrect detachable medium label. 
(error_tabl e_$bad__l abel ) 

Meaning: there is an inconsistency or error in the label on 
this detachable volume. 
Indicated device assigned to another process. 
(error__tabl e__$al ready_ass i gned ) 

Meaning: The indicated device is already assigned to 
another process. 
Infinite recursion. 

(error_tabl e_$recurs ion__error) 

Meaning: Recursive include segments were encountered while 
expanding a source segment. 
Initial connection socket is in an improper state. 
(error_tabl e__$net_i pc__bad__state) 

Meaning: Network only. The user's process had made a call 
to a Network connection management program (such as 
net_icp_) to establish a socket connection to a foreign 
host, and some anomalous event has occurred which has left 
the user's local (Multics) socket in an improper state. The 
connection attempt should be re-tried; if the problem 
persists, it should be reported. 
Insufficient access to return any information, 
(er ror_tabl e_$no_i nf o) 

Meaning: The user had insufficient access to the specified 
entry or to its superior directory to return any information 
about the entry. 
Internal index out of bounds. 
(error_table_$bad__i ndex) 

Meaning: The device index given does not correspond to a 
device owned by this process. 
Invalid backspace_read order call. 

(er ror_tabl e_$ i nval i d__backspace_read) 

Meaning: The backspace_read request attempts to set the 
read reference pointer of an I/O system stream to the 
element after the previous read delimiter; however, no read 
delimiters currently exist for the given stream. 
Invalid element size. 

(er ror_tabl e_$ i nva 1 i d_el size) 

Meaning: The element size specified in this I/O system call 
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is not valid for the type of device associated with the 
specified stream. 
Invalid mode specified for ACL. 
(error_table__$ i nval i d_mode) 

Meaning: The user attempted to set m (modify) permission on 
a directory without setting s (status) permission. 

Invalid move of quota would change terminal quota to non 

termi nal . 

(error_tabl e_$ i nval i d_move_quota ) 

Meaning: An attempt was made to move all assigned quota to 
a superior directory when the quota is still used in an 
inferior directory. 
Invalid project for gate access control list, 
(er ror__tabl e_$ i nval i d__proj ect__f or gate) 

Meaning: Access to gates can only be set for users in the 
same project. 
Invalid volume identifier. 

(error_tabl e_$bad_vol i d or error_table_$bad_tapeid) 
Meaning: The specified detachable volume name is incorrect 
or does not match the volume name stored in the volume 
1 abel . 

loname already attached and active. 
(error__tabl e_$ i onmat ) 

Meaning: An attempt has been made to attach an I/O device 
to a stream to which no more devices can be attached, 
loname not active. 

(error__table_$ i oname_not_act i ve) 

Meaning: The stream name specified in a call to the I/O 
system is not attached to any device. Either the specified 
stream name or one of the stream names to which it is 

attached through on intermediate outer module should be 
attached to a device, 
loname not found. 

( e r ror_tab 1 e_$ i oname_not_f ound ) 

Meaning: No stream with the stream name given in the call 
to the I/O system exists. 
Linkage section not found. 

(error__table_$no_l inkage) 

Meaning: Either a data segment has been called or a bad 
object segment referenced. 
Looping searching definitions, 
(er ror_tabl e_$def s__loop) 

Meaning. There were too many definitions found in the 
definitions search. The user should try reducing the number 
of entry names in the segment. It is also possible that the 
linkage information has been illegally modified to produce a 
c i rcular list. 
Maximum number of arguments for this command exceeded. 
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(error_tabl e_$ too_many_args ) 

Meaning: A command which has a maximum on some argument set 
was called with more arguments of that type than are 
al lowed. 
Mismatched iteration sets. 

(er ror_tabl e__$mi smatched_i ter ) 

Meaning: The command line contains more than one iteration 
element and the number of iterations specified by one is not 
the same as specified by another. 
Missing entry in outer module. 
(error_table_$missent ) 

Meaning: The I/O system call is not implemented for the 
type of device associated with the stream specified in the 
cal 1 . 

Mount request could not be honored. 

(er ror_tabl e__$bad_mount_request ) 

Meaning: Some error has occurred while attempting to 
perform this mount request. 
Mount request pending 

(er ror_tabl e_$mount_pend i ng) 

Meaning: The volume requested is currently being mounted as 
requested; i.e./ this is a redundant request. 
Multics IMP is down. 

(er ror_tabl e_$ i mp_down ) 

Meaning: Network only. The Interface Message Processor 
that connects Multics to the Network is not operating. All 
connections with other Network hosts have been broken, and 
no new connections can be established until the IMP resumes 
communication with Multics. 
Name already on entry. 

(error_tabl e_$segnamedup) 

Meaning: An attempt was made to add a name to a storage 
system entry when the name was already on that entry. 
Name dupl i cat ion. 

(er ror_table_$namedup) 

Meaning: An attempt was made to add a name to a storage 
system entry when the name was already on some other entry 
in the same directory. 
Name list exceeds maximum size. 

( e r ror_tabl e_$ too_many_names ) 

Meaning: From get_J ibrary_source: The user specified too 
many source segment names or system names. 
Name not found. 

(error_tabl e_$ol dnamerr ) 

Meaning: An attempt was made to delete from a storage 
system entry a name that was not on that entry. 
Negative number of elements supplied to data transmission entry. 
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(er ror_tabl e_$negat i ve_nel em) 

Meaning: A negative number of elements specified in an I/O 
system call is not permitted. 
Negative offset supplied to data transmission entry. 
(error_ table_$negat i ve_of f set) 

Meaning: Negative offsets to I/O system read or write calls 
are not permitted. 
Network connection closed by foreign host, 
(er ror_tabl e_$net_socket_closed) 

Meaning: Network only. A previously open Network 
connection to a foreign host has been disconnected by that 
host; communication over that connection has been 
terminated. 
Network control program not in operation. 
(error_tabl e_$net__not_up) 

Meaning: Network only. The user has attempted to establish 
a Network connection to a foreign host, but Multics is not 
presently communicating with the Network. 
New offset for pointer computed by seek entry is negative. 
(error__tabl e_$new_of f set_negat i ve) 

Meaning: The value of a reference pointer relative to the 
first reference pointer can never be negative. The 
specified seek call would have resulted in such a negative 
offset . 

No PRPH card was found for the requested device. 
(error_tabl e__$no_prph_card) 

Meaning: No PRPH (peripheral) card was found in the 
configuration deck for the requested device. 
No bases supplied in force call. 
(error_tabl e_$f orce_bases ) 

Meaning: Insufficient information was supplied to complete 
an Indirect Through Base (ITB) link. 
No device currently available for attachment. 
( e r ro r_ta b 1 e_$ no_dev i ce ) 

Meaning: No free device is currently available for 
attachment by this process. 
No interrupt was received on the designated 10 channel. 
(error_ table_$no_io_ i nterrupt ) 

Meaning: The DCW list active switch in the printer DCM had 
not been turned off in 100,000 tests of its status. 
No linkage offset table in this ring. 
( e r r o r_ta b 1 e_$ no 1 o t ) 

Meaning.: There is no linkage offset table in this ring. 
No room available for device status block. 
( e r ro r_t a b 1 e_$ no_room__f o r__ds b ) 

Meaning: The attachment could not be performed because 
space for the necessary data was not available. This 
problem might be corrected by detaching another stream 
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associated with the same type of device. 
No wired structure could be allocated for this device request. 
(error = tabl e^Sno^wi red_structure) 

Meaning: All available wired structures for this device 
type were in use when the device attachment was attempted. 
No/bad linkage info in the lot for this segment. 
(error_tabl e_$nol inkag) 

Meaning: The system could not find the linkage information 
for a segment. 
Not enough room in stack to complete processing. 
(error__tabl e_$stack_overf low) 

Meaning: The request specified by the user requires too 
many recursive calls to be processed; e.g., by the command 
processor . 

Not in proper ring bracket to perform desired operation, 
(er ro r__tabl e_$not_i n_p rope r__b racket ) 

Meaning: The ring brackets, independently of the access 
modes, prevent the desired access to a segment. 
Null bracket set encountered. 

(error_tabl e_$nul l_brackets) 

Meaning: An active string of the form was encountered. 
Obsolete object segment format, 
(er ror_tabl e_$ol dobj ) 

Meaning: The object segment being referenced is in an 
obsolete format. 
Odd number of arguments. 

(error_tabl e_$odd_no_of„args ) 

Meaning: An attempt was made to call a command that 
requires pairs of arguments with an odd number of arguments. 
Parentheses do not balance. 

(error__tabl e_$unbal anced_paren theses ) 

Meaning: The parentheses in a command line do not balance. 
Pathname too long. 

(error__tabl e_$ path long) 

Meaning: Total path name is longer than 168 characters. 
Physical end of device encountered. 
(error_tabl e_$dev i ce_end) 

Meaning: The physical end of the device (e.g., magnetic 

tape) was encountered. 
Pointer name passed to seek or tell not currently implemented by 
it. 

( e r ro r__t a b 1 e_$ u n i mp 1 erne n t ed_p t r name ) 

Meaning: The pointer name passed to the seek or tell call 
is not currently implemented by it. 
Procedure called improperly. 
(error__tabl e_$badcal 1 ) 

Meaning: The procedure was called improperly. 
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Procedure was not invoked as an active function, 
(er ror_tabl e_$not_act_f nc) 

Meaning: A procedure that is intended to be used as an 
active function was invoked as a normal command. 
Process lacks permission to alter device status. 
( e r ro r_t ab 1 e_$ i o_no__pe rm i s s i on ) 

Meaning: The user attempted to do something to an I/O 
device that does not belong to him. 
Process not attached to indicated device, 
(er ror__table_$not_attached) 

Meaning: The process is not attached to the indicated 
device. 
Quotes do not balance. 

(error_table_$unba1 anced__quotes ) 

Meaning: The quotes in a command line do not balance. 
Record quota overflow. 

(er ror_tabl e_$ rqover ) 

Meaning: An attempt was made to use more records than the 
user is permitted by the storage system. 
Relevant data terminated improperly. 

(error_tabl e_$data_improperl y_termi nated) 

Meaning: From tape__: the end of readable data was reached 
on read, but the tape had not been properly detached when 
data was written. 
Request for connection refused by foreign host. 
(error_tabl e_$net__rf c_ref used) 

Meaning: Network only. The user has requested a Network 
connection to a particular socket at a foreign host, and the 
foreign host has refused that connection request. It may be 
that the foreign host is not offering the desired Network 
service at this time, or that no process on that foreign 
host is listening for connection requests on that socket. 
Request for connect received from improper foreign socket, 
(er ror_tabl e_$net_bad_connect ) 

Meaning: Network only. The user's process was waiting to 
complete a connection to a foreign Network host, but the 
connection established was not the expected one. The 
connection attempt was therefore abandoned. The user should 
try again. 

Request is inconsistent with current state of device, 
(er ror_tabl e__$ inval id_state) 

Meaning: The operation requested is not possible because 

the specified device is in a state inconsistent with that 
operat i on . 

Request is inconsistent with state of socket. 
(error_table_$net_inval i d_state) 

Meaning: Network only. Some operation could not be 
performed on the user f s Network connection, because the 
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present state of the connection does not allow it. For 
example/ it is not possible to read or write on a Network 
socket that is not connected to a foreign Network host. 
Request not recognized. 

(error_table_$request_not__recogn i zed) 

Meaning: The user requested a program to perform an action 
that it was not prepared to perform. 
Requested tape backspace unsuccessful . 
(er ro r__tabl e__$no__back space) 

Meaning: From nstd_ : An unsuccessful backspace to retry 
writing the record after a bad transmission occurred. 
Requested volume is already mounted. 
(error_tabl e_$ redundant_jnount ) 

Meaning: The tape reel or other volume of detachable nature 
is already mounted on the drive requested. 
Requested volume is not yet mounted, 
(er ror_tabl e__$mount_not__ready ) 

Meaning: The tape real or other volume of detachable nature 
is still being mounted on the drive requested. 
Ring brackets input to directory control are invalid. 
(error_tabl e__$bad__r i ng_brackets ) 

Meaning: The ring brackets to be added to an ACL are 
inconsistent or illegal. 
Segment already known to process, 
(er ror__tabl e_$segknown) 

Meaning: The segment is already known to the process and 
the information returned by the call should be assumed to be 
val i d. 
Segment is not bound. 

(error_tabl e_$not__bound) 

Meaning: The referenced segment is not a bound segment. 
Segment not found. 

(error_tabl e_$seg_not_f ound) 

Meaning: The segment was not found using the user's search 
rul es . 

Segment not known to process. 

(er ror_tabl e_$seg_un known) 

Meaning: The user has attempted to terminate a segment that 
is not known to this process. 
Segment not of type specified. 

(er ror_tabl e_$not_seg_type) 

Meaning: The segment specified as an argument was not of 
the type expected; e.g., a segment specified to the mail 
command as a mailbox was actually a directory. 
Some directory in path specified does not exist, 
(er ror_tabl e_$no_di r ) 

Meaning: The user specified a path name containing a 
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directory that does not exist. 
Specified buffer size too large. 
(error__tabl e__$buf fer_bi g) 

Meaning: From nstd__: too large a read/write request was 
passed to the Hardcore Ring tape DCM. 
Specified control argument is not implemented by this command. 
(error_table__$badopt ) 

Meaning: A control argument was used that is not applicable 
to this particular command or, perhaps, a valid control 
argument was misspelled. 
Specified offset out of bounds for this device, 
(er ror__tabl e__$dev__of f set__out__of__bounds ) 

Meaning: From tape__: A nonzero offset was passed to the 
seek request. 
Specified socket not found in network data base, 
(er ror__tabl e__$ne t__socket_.no t__found) 

Meaning: Network only. An attempt has been made to perform 
an operation on a Network socket connection of that the 
Multics Network Control Program has no record. A 
now-invalid socket identifier may have been retained from a 
previous invocation of some program in the user's process. 
Status permission missing on directory containing entry, 
(er ror__tabl e_$no_s__permi ss ion ) 

Meaning: The user attempted to access an entry in a manner 
requiring s (status) permission on the superior directory 
when he did not have permission to that directory. 
Strings are not equal. 

(er ror__tabl e__$str i ngs__not__equal ) 

Meaning: Character or bit strings that should be equal were 
not equal . 

Supplied area too small for this request, 
(er ror__tabl e__$area_too__smal 1 ) 

Meaning: The supplied area is too small for this request. 
Supplied identifier already exists in data base, 
(er ror__tabl e__$ id__al ready__exi sts) 

Meaning: An identifier that must only appear once in a data 
base has appeared more than once. 
Supplied machine conditions are not restartable. 
(er ror_tabl e__$no_res tart ) 

Meaning: The user attempted to restart (using the start 
command) after a fault that cannot be restarted because the 
machine conditions are invalid. 
Symbol segment not found. 

( e r r o r__ t a b 1 e__$ no__s y m__s eg ) 

Meaning: The symbol segment was not found. 
Syntax error in ascii segment. 
(error__tabl e__$badsyntax) 

Meaning: There was a syntax error in an ASCII segment. 
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System service process not currently available. 
(error_table_$nosys ) 

Meaning: The requested service normally provided by the 
system cannot be used at this time. 
The NCP could not find a free table entry for this request. 
(error_table_$net_tabl e_space) 

Meaning: Network only. A system-wide data base maintained 
by the Network Control Program is full, and no more Network 
connections can be established at this time. If this 
problem persists, it should be reported so that increasing 
Network traffic can be accommodated. 
The access name specified has an illegal syntax, 
(er ror_tabl e_$bad_name) 

Meaning: An access control name was encountered that was 
not of the form "person_id. projected, tag." 
The directory hash table is full. 
(error_tabl e_$f ul l_hashtbl ) 

Meaning: A user has tried to add two many names within a 
directory. (This will not be restricted in the future and 
the status code will no longer be returned.) 
The directory is the ROOT. 
( e r ro r_tab 1 e_$ roo t ) 

Meaning: The root has no branch and therefore, the 
requested operation does not work for this directory. 
The equal name specified had illegal syntax, 
(er ror_tabl e_$bad_equal__name) 

Meaning: An equal name: 1) had more than one == component; 
2) contained a < or >character; 3) had an illegal character 
(e.g., tab or new line); k) had more than one s in a 
component that was not == ; or 5) had a null component. 
The event channel specified is not a valid channel. 
(error_tabl e_$ inval i d_channel ) 

Meaning: A channel name was supplied to i pc_ that does not 
correspond to an existing event channel. 
The event channel table was full. 
(error_tabl e__$ect_f ul 1 ) 

Meaning: No more event channels can be created in the 
current ring unless some existing channels are deleted. 
The event channel table was in an inconsistent state, 
(er ror_tabl e_$ i neons i stent_ect ) 

Meaning: There is an inconsistency in the data bases of 
ipc_, probably resulting from interrupting ipc__ while it was 
running. A new process is recommended. 
The initial connection has not yet been completed, 
(er ror_tabl e_$net_i pc_not_concl uded ) 

Meaning: Network only. The user's process has made a call 
to a Network connection management program (such as 
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net__ipc_) to gain control over a socket connection on which 
a connection attempt has been initiated but has not yet been 
completed. The user's process should wait for a wakeup from 
the connection management program before making this call. 
The lock could not be set in the given time. 
(error_tabl e_$ lock__wa i t_time_exceeded) 

Meaning: An attempt was made to lock a lock already locked 
by another process and the lock was not relinquished to the 
current process in the specified amount of time. 
The lock was already locked by this process, 
(er ror_tabl e_$ locked_by_th i s_process ) 

Meaning: An attempt was made to lock a lock that was 

already locked by the current process. 
The lock was locked by a process that no longer exists, therefore 
the lock was reset. 

(er ror__tabl e_$ inval id_lock_reset ) 

Meaning: An attempt was made to lock a lock that was 
already locked by another process; however, the other 
process does not currently exist so the lock was forcibly 
locked for the current process. 

The maximum depth in the storage system hierarchy has been 

exceeded. 

(er ror_tabl e__$max_depth__exceeded) 

Meaning: The maximum depth of the storage system hierarchy 
is 16 levels. An attempt was made to create an entry at a 
deeper 1 evel . 
The name specified contains non-ascii characters. 
(error__tabl e_$ i nval i d_asc i i ) 

Meaning: The user specified an access control name which 
contains non-ASCII characters. 
The name was not found. 

(er ror__tabl e_$name_not__f ound) 

Meaning: The entry name specified by the user was not found 

i n the d i rectory . 
The normal /ge-xtnd switch is set incorrectly on the printer 
control 1 er . 

(error_tabl e__$pr i nt_mode_swi tch ) 

Meaning: The switch on the printer controller governing the 
normal or ge-xtnd mode setting is set incorrectly. 
The operation would leave no names on entry. 
(error_tabl e__$nonamerr ) 

Meaning: An attempt has been made to delete the last name 
on a storage system entry. 
The process's limit for this device type is exceeded, 
(er ror_tabl e_$dev i ce_l imi t_exceeded) 

Meaning: From tape_: the caller already has attached to 
his process the maximum number of drives allowed to be 
assigned at any one time. 
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The reference name count is greater than the number of reference 
names . 

(er ror__tabl e_$ref name_count_too_Jbi g) 

Meaning: The reference name count is greater than the 
number of reference names on an initiated segment. 
The requested action was not performed, 
(er ror__tabl e_$act ion_not_per formed) 

Meaning: The user requested some action but either 1) had 
previously directed the program to perform only certain 
other actions/ or 2) directed the program to not perform the 
action when questioned about it. 
The rest of the tape is blank, 
(er ror_tabl e_$bl ank__tape) 

Meaning: From tape__: an attempt was made to read a blank 
tape (returned only by the attach request). 
The same fault will occur again if restart is attempted. 
(error_tabl e__$useless_restart ) 

Meaning: The user attempted to restart (using the start 

command) after a fault that should not be restarted because 

it will recur immediately. 
The specified detachable volume has not been registered, 
usel ess_res tart 

The same faule occur again if restart is attempted. 

(er ror_tabl e_$unreg i s tered_vol ume) 

Meaning: The tape reel or other detachable volume has not 
been registered with Multics Operations/ and therefore 
cannot be user 

The star convention is not implemented by this procedure. 
(error_table__$nostars) 

Meaning: This procedure does not allow any special 
characters in name arguments. 
The stream is attached to more than one device. 
( e r ro r_tab 1 e_$mu 1 1 i p 1 e_i o_a t tachmen t ) 

Meaning: The specified stream was associated with more than 
one device when the attempt was made to get information 
about it. Therefore/ not all the associations could be 
returned . 

There are too many links to get to a branch. 
(error_tabl e_$ toomany 1 inks) 

Meaning: The number of links traversed to refer to a branch 
has exceeded the system limit (currently 10). 
There is an inconsistency in arguments to the file system. 
(error__tabl e__$argerr ) 

Meaning: The arguments given were incorrect because of 
type, number, and/or format. 
There is an internal inconsistency in the segment, 
(er ror_tabl e_$bad_segment ) 
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Meaning: From obj ect_i nf o__: the segment is not an object 
segment. From message segment facility: the message 
segment was being salvaged or was left in an inconsistent 
state (perhaps due to a system crash). 
There is no initial connection in progress from this socket, 
(er ror_table_$net__no_J cp) 

Meaning: Network only. The user's process has made a call 
to a Network connection management program (such as 
net_jcp_) to gain control over a socket connection without 
having previously called this program to initiate that 
connection. This may indicate a programming error in the 
user-level Network interface program being used. 
There is no more room in the KST. 
(er ror_tabl e_$nrmkst ) 

Meaning: There is no more room in the KST to allocate KST 
entries. A solution for this problem is to terminate 
segments, terminate reference names, or to cause a new 
process to be created. 
There is no room to make requested allocations. 
(error_table_$noal loc) 

Meaning: The user-specified area for return arguments is 
not large enough, or the user attempted to add an entry to a 
directory that had no room for additional entries. 
There was an attempt to create a copy without correct access, 
(er ror_tabl e_$ i nval i d_copy ) 

Meaning: An attempt has been made to initiate a directory 
with the copy switch on. 
There was an attempt to delete a non-empty directory. 
(error_tabl e__$f ul ldi r) 

Meaning: The user attempted to delete a directory that 

contains branches and/or links. 
There was an attempt to make a directory unknown that has 
inferior segments. 

(er ror_tabl e_$ i nf cnt_non_zero) 

Meaning: There was an attempt to make a directory unknown 
that has inferior segments known. 
There was an attempt to move segment to non-zero length entry. 
(error_table_$cl nzero) 

Meaning: The user called hcs_$f s_move_f i 1 e or 
hcs_$f s_move_seg and specified a nonzero length segment as 
the entry to move to and did not specify the truncate 
swi tch. 

There was an attempt to use an invalid segment number. 
(error_tabl e_$ i nval i dsegno) 

Meaning: The user attempted to use a pointer that contained 
a segment number that does not reference any segment known 
to his process. 
This operation is not allowed for a directory. 
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(error_tabl e_$di rseg) 

Meaning: The attempted operation is illegal when performed 
on a directory. 
This operation is not allowed for a segment. 
(error_table_$nondi rseg) 

Meaning: The attempted operation is illegal when performed 
on a segment. 

This procedure does not implement the requested version. 
(error_tabl e_$un impl emented_vers i on) 

Meaning: The version number on a data structure is unknown 
to the system module attempting to manipulate the data, 
indicating that the data might not be in the expected 
format. 

Too many "<" 1 s in pathname. 
(error_tab1e_$ 1 esserr ) 

Meaning: The user supplied a relative path name that 
contains more less than characters than his current working 
directory is deep in the hierarchy. 
Too many buffers specified. 

(error_tabl e_$too_many_buf f ers ) 

Meaning: Not enough wired core exists to transfer the 
requested data. 
Too many read delimiters specified. 

(error_table_$ too_many_read__.de 1 imi ters ) 

Meaning: The type of device associated with the given 
stream does not support the given number of read delimiters 
or break characters at the current element size. It may be 
possible to specify fewer read delimiters or break 
characters . 
Too many search rules. 

(error_tabl e_$too_many_sr ) 

Meaning: The number of search rules to be used exceeds the 
system limit. 
Translation failed. 

(error_tabl e_$translat ion_f ai 1 ed) 

Meaning: The translation was not able to produce a usable 
object segment because of errors in the source segment. 
Typename not found. 

(error_tabl e_$ typename_not_f ound) 

Meaning: The device type specified in a call to the I/O 
system is unknown. 
Unable to convert character date/time to binary. 
(error_tabl e_$date_convers ion_error ) 

Meaning: Illegal syntax or conflicting specifications were 
used in the input string that specifies the date/time. 
Unable to create a copy. 

(error_tabl e_$no_create_copy ) 
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Meaning: A copy of the desired segment could not be 
created. 
Unable to initiate the copy. 

(er ror_tabl e_$copy__not_i ni t ) 

Meaning: The copy of the desired segment cound not be 
ini t iated. 

Unable to make original segment known. 
( e r ro r_t a b 1 e_$ no_make known ) 

Meaning: A segment with a copy switch on could not be 
initiated and, hence, no copy could be made. 
Unable to move segment because of type, access or quota. 
( e r ro r_ta b 1 e_$ no__mov e ) 

Meaning: The segment could not be moved because of type, 
access or quota. 
Unable to process a search rule string, 
(er ror__table_$bad_str i ng) 

Meaning: The syntax in a search rule string is 
unacceptabl e. 
Unable to set the bit count on the copy. 
(error_table_$no_set_btcnt ) 

Meaning: The bit count on the copy of the desired segment 
could not be set. 
Undefined order request. 

(er ror_tabl e_$undef i ned_order_reques t ) 

Meaning: The request specified in this I/O system order 
call does not exist for the type of device associated with 
the given stream name. 
Unrecognizable ptrname on seek or tell call, 
(er ror„tabl e_$undef ined__ptrname) 

Meaning: An invalid reference pointer name was given in an 
I/O system seek or tell call. 
Unrecoverable data-transmission error on physical device. 
( e r r o r_t a b 1 e_$dev i ce_pa r i t y ) 

Meaning: From tape_: the program was physically unable to 
finish writing the tape or unable to read the desired tape 
record. If another read request is made, processing begins 
with the next logical record. 
Use of star convention resulted in no match. 
(error__tabl e__$ noma ten) 

Meaning: The use of the star convention resulted in no 
match during the requested directory search. 
User name not on access control list for branch. 
(error_table_$user_not_found) 

Meaning: A storage system subroutine for deleting or 
listing ACL entries could not find a name that was 
requested . 
Wrong number of arguments supplied, 
(er ror_tabl e_$wrong_no_of_args) 
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Meaning: A program was not passed the correct number of 
arguments. 
Zero length segment. 

(er ro r_tabl e_$zero__l ength_seg) 

Meaning: The bit count of the segment indicates that it is 
of zero length. 
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The following is an alphabetic cross-reference by 
error_table_ entry name to printed messages listed in the first 
part of this write-up. The er ror_tabl e„$ prefix has been removed 
from these entry names to facilitate perusing. 



ac t i on__not_perf ormed 

The requested action was not performed, 
al ready__ass i gned 

Indicated device assigned to another process. 
area_too_smal 1 

Supplied area too small for this request. 
arg_ignored 

Argument ignored, 
arger r 

There is an inconsistency in arguments to the file system. 
att_l oop 

Attachment loop. 
bad_acl_mode 

Bad mode specification for ACL/CACL. 
bad_arg_acc 

Improper access to given argument. 
bad_arg__type 

Bad gate for entry referenced. 
bad_cl ass_def 

Bad class code in definition. 
bad_command_name 

Improper syntax in command name. 
bad_ent ry__po i nt__name 

Illegal entry point name in make_ptr call, 
b a d _e q u a 1 __n a m e 

The equal name specified had illegal syntax 
bad__i ndex 

Internal index out of bounds. 
bad__l abel 

Incorrect detachable medium label. 
bad_l i nk_target_i ni t_info 

Illegal initialization info passed with create- i f-not-found 

1 i nk. 
bad_l i nk_type 

Illegal type code in type pair block. 
bad_mode 

Improper mode specification for this device. 
bad_mount__request 

Mount request could not be honored. 
bad_ms__ convert 

Attempt to convert directory or link to multisegment file. 
bad_ms_f i 1 e 
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Directory or link found in multisegment file. 
bad_name 

The access name specified has an illegal syntax. 
bad_ process i d 

Current processid does not match stored value. 
bad_pt r 

Argument is not an ITS pointer. 
bad_r i ng__b r a c ke t s 

Ring brackets input to directory control are invalid. 
bad_segment 

There is an internal inconsistency in the segment. 
bad_sel f_ref 

Illegal self reference type. 
bad_st r i ng 

Unable to process a search rule string. 
bad_tapeid 

Invalid volume identifier. 
bad__vol i d 

Invalid volume identifier, 
badcal 1 

Procedure called improperly, 
badequal 

Illegal use of equals convention, 
badopt 

Specified control argument is not implemented by this 

command, 
badpath 

Bad syntax in pathname, 
bads tar 

1 1 1 egal entry name, 
badsyntax 

Syntax error in asci i segment, 
bi garg 

Argument too long, 
bl ank__tape 

The rest of the tape is blank, 
boundviol 

Attempt to access beyond end of segment, 
buf fer_bi g 

Specified buffer size too large. 
change_f i rst 

Attempt to change first pointer, 
cl nzero 

There was an attempt to move segment to non-zero length 
entry. 
command_J i ne__ove r f 1 ow 

Expanded command line is too large. 
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copy__not__ini t 

Unable to initiate the copy. 
dart_abort 

Dartmouth job aborted, 
da ta__imp roper 1 y_termi nated 

Relevant data terminated improperly. 
date_convers ion__er ror 

Unable to convert character date/time to binary, 
def s__loop 

Looping searching definitions. 
dev__nt_assnd 

10 device not currently assigned. 
dev_pf f set_out__pf_bounds 

Specified offset out of bounds for this device, 
dev i ce_end 

Physical end of device encountered, 
devi ce__l imi t_exceeded 

The process's limit for this device type is exceeded. 
device_par i ty 

Unrecoverable data-transmission error on physical device, 
di rlong 

Directory pathname too long, 
di rseg 

This operation is not allowed for a directory. 
dup__ent_name 

Duplicate entry name in bound segment. 
ect_ful 1 

The event channel table was full. 
empty_acl 

ACL/CACL is empty, 
ent long 

Entry name too long. 
execute__data 

Attempt to execute in data segment. 
force__bases 

No bases supplied in force call, 
ful ljiashtbl 

The directory hash table is full, 
fulldir 

There was an attempt to delete a non-empty directory, 
i d_al ready_ex i sts 

Supplied identifier already exists in data base, 
i mp_down 

Multics IMP is down, 
i mpr ope r_da ta__f o rma t 

Data not in expected format, 
i neons i stent 

Inconsistent combination of control arguments. 
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incons i stent_ect 

The event channel table was in an inconsistent state, 
i ncorrect_access 

Incorrect access to directory containing entry, 
inf cnt_non_zero 

There was an attempt to make a directory unknown that has 

inferior segments, 
inval i d_asci i 

The name specified contains non-ascii characters, 
inval i d__backspace_read 

Invalid backspace_read order call, 
inval i d_channel 

The event channel specified is not a valid channel, 
inval i d__copy 

There was an attempt to create a copy without correct 

access . 
inval id_device 

Attempt to attach to an invalid device, 
i nval i d__el si ze 

Invalid element size, 
inval i d_Jock_reset 

The lock was locked by a process that no longer exists/ 

therefore the lock was reset, 
inval i d_max__l ength 

Attempt to set max length of a segment less than its current 

length, 
i nva 1 i d_mode 

Invalid mode specified for ACL. 
i nva 1 i d_move_quota 

Invalid move of quota would change terminal quota to non 

termi nal . 
i nval i d_proj ect_for_gate 

Invalid project for gate access control list, 
i nval i d_read 

Attempt to read or move read pointer on device which was not 

attached as readable, 
inval i d_seek_last__bound 

Attempt to manipulate last or bound pointers for device that 

was not attached as writeable. 
inval i d_setdel im 

Attempt to set delimiters for device while element size is 

too large to support search. 
Inval i d__state 

Request is inconsistent with current state of device, 
i nval i d_wr i te 

Attempt to write or move write pointer on device which was 
not attached as writeable. 
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i nval i dsegno 

There was an attempt to use an invalid segment number, 
i o_ no_pe rm i s s i on 

Process lacks permission to alter device status. 
io_st i 1 l_assnd 

10 device failed to become unassigned. 
ioat_ er r 

Error in internal ioat information. 
ioname_not_act i ve 

loname not active. 
ioname__not_f ound 

loname not found, 
ionmat 

loname already attached and active. 
1 esserr 

Too many "<" 1 s in pathname. 
lock__not__ locked 

Attempt to unlock a lock that was not locked. 
lock__wa i t__t ime__exceeded 

The lock could not be set in the given time. 
locked_by_other_process 

Attempt to unlock a lock which was locked by another 

process . 
locked_by_th i s__process 

The lock was already locked by this process, 
longeql 

Equals convention makes entry name too long, 
loterr 

Error zeroing entry in the linkage offset table. 
max_depth_exceeded 

The maximum depth in the storage system hierarchy has been 

exceeded, 
mi smatched_i ter 

Mismatched iteration sets, 
mi ssent 

Missing entry in outer module, 
moderr 

Incorrect access on entry. 
mount_not__ready 

Requested volume is not yet mounted. 
mount_pend i ng 

Mount request pending, 
mul t iple_io_attachment 

The stream is attached to more than one device. 
name__not_f ound 

The name v/as not found, 
namedup 

Name duplication, 
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negat i ve_nelem 

Negative number of elements supplied to data transmission 

entry, 
negat ive_off set 

Negative offset supplied to data transmission entry. 
net_al ready_i cp 

An initial connection is already in progress from this 
socket. 
net_bad_connect 

Request for connection received from improper foreign 

socket . 
net_bad__gender 

Bad socket gender involved in this request. 
net_bad_hos t 

Illegal host number or id. 
net_f hos t_down 

Foreign host is down. 
net_f hos t__i nact i ve 

Communications with this foreign host not enabled, 
ne t__f i mp__down 

Foreign IMP is down. 
net_i pc_bad_state 

Initial connection socket is in an improper state. 
net__i pc_error 

A logical error has occurred in initial connection. 
net_i cp_not_concl uded 

The initial connection has not been completed. 
net_i nval i d_state 

Request is inconsistent with state of socket. 
net_no_i cp 

There is no initial connection in progress from this socket. 
net_not_up 

Network control program not in operation. 
net_rf c__ref used 

Request for connection refused by foreign host. 
net_socket_closed 

Netword connection closed by foreign host. 
net_socket_not_f ound 

Specified socket not found in network data base. 
net_tabl e_space 

The NCP could not find a free table entry for this request. 
net_t imeout 

Connection not completed within specified time interval. 
new__of f set_negat i ve 

New offset for pointer computed by seek entry is negative. 
no__append 

Append permission missing. 
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no_backspace 

Requested tape backspace unsuccessful. 
no__create_copy 

Unable to create a copy. 
no__def s 

Bad definitions pointer in linkage. 
no_dev i ce 

No device currently available for attachment. 
no_d i r 

Some directory in path specified does not exist. 
no__ext_sym 

External symbol not found. 
no__i nf o 

Insufficient access to return any information. 
no_io_i nter rupt 

No interrupt was received on the designated 10 channel. 
no_job_core 

Could not create dartmouth job core. 
no__l i nkage 

Linkage section not found. 
no_make known 

Unable to make original segment known. 
no__move 

Unable to move segment because of type, access or quota. 
no__prph_card 

No PRPH card was found for the requested device. 
no_restart 

Supplied machine conditions are not restartable. 
n o_ r oom_f o r _d s b 

No room available for device status block. 
no_s_permi ss i on 

Status permission missing on directory containing entry. 
no_set_btcn t 

Unable to set the bit count on the copy. 
no_sym_seg 

Symbol segment not found. 
no_wi red_st ructure 

No wired structure could be allocated for this device 

request, 
noal loc 

There is no room to make requested allocations. 

noarg 

Expected argument missing, 
nodescr 

Expected argument descriptor missing, 
noent ry 

Entry not found, 
nol i nkag 
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No/bad linkage info in the lot for this segment. 

nolot 

No linkage offset table in this ring, 
noma ten 

Use of star convention resulted in no match, 
noname rr 

The operation would leave no names on entry, 
nondi rseg 

This operation is not allowed for a segment, 
nostars 

The star convention is not implemented by this procedure. 

nosys 

System service process not currently available, 
not __a_.br an ch 

Entry is not a branch. 
not_act_f nc 

Procedure was not invoked as an active function. 
not__attached 

Process not attached to indicated device. 
not__bound 

Segment is not bound. 
not_J n_.p rope r__b racket 

Not in proper ring bracket to perform desired operation. 
not_seg_type 

Segment not of type specified, 
notadi r 

Entry is not a directory, 
notal loc 

Allocation could not be performed, 
nrmkst 

There is no more room in the KST. 
nul l_brackets 

Null bracket set encountered. 
odd__no_pf _a rgs 

Odd number of arguments, 
ol dnamerr 

Name not found, 
ol dobj 

Obsolete object segment format. 
out_of_sequence 

A call that must be in a sequence of calls was out of 

sequence, 
pathlong 

Pathname too long, 
pr i nt__mode_swi tch 

The normal /ge-xtnd switch is set incorrectly on the printer 

control ler . 
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recurs ion_error 

Infinite recursion. 
redundant_mount 

Requested volume is already mounted, 
ref name_count_too_b i g 

The reference name count is greater than the number of 

reference names. 
request_not_recogn i zed 

Request not recognized. 

root 

The directory is the ROOT, 
rqover 

Record quota overflow, 
saf ety_sw_on 

Attempt to delete segment whose safety switch is on. 
sameseg 

Attempt to specify the same segment as both old and new. 
seg_not_f ound 

Segment not found. 
seg__unknown 

Segment not known to process, 
segknown 

Segment already known to process, 
segnamedup 

Name already on entry, 
smal larg 

Argument size too small. 
stack_overf low 

Not enough room in stack to complete processing, 
str i ngs_not_equal 

Strings are not equal. 
too_many_args 

Maximum number of arguments for this command exceeded, 
too_jnany_buf f ers 

Too many buffers specified. 
too_ma n y__n ame s 

Name list exceeds maximum size. 
too_many_read_de1 imiters 

Too many read delimiters specified. 
too_ many_sr 

Too many search rules, 
toomany 1 i nks 

There are too many links to get to a branch, 
translat ion__aborted 

Fatal error. Translation aborted, 
translat ion_f a i led 

Translation failed. 
typename__not_f ound 
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Typename not found. 
unbalanced_b rackets 

Brackets do not balance. 
unbalanced_paren theses 

Parentheses do not balance, 
unba 1 anced_quotes 

Quotes do not balance, 
undef ined__order_request 

Undefined order request, 
undef i ned_pt rname 

Unrecognizable ptrname on seek or tell call, 
u n i mp 1 emen t e d_p t r name 

Pointer name passed to seek or tell not currently 

implemented by it. 
un i mp 1 emented_ve rs i on 

This procedure does not implement the requested version, 
unregi stered_vol ume 

The specified detachable volume has not been registered, 
usel ess_restart 

The same fault will occur again if restart is attempted. 
user_not_found 

User name not on access control list for branch. 
wrong_channel_r i ng 

An event channel is being used in an incorrect ring, 
w r o n g_n o_o f _a r g s 

Wrong number of arguments supplied, 
ze ro_l ength_seg 

Zero length segment. 
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li Si Or o Y o i cM uuhu i i i uNb ANu ucrAu l i uN u N i i mi i i uNo 

System conditions are signalled to report certain unusual 
occurrences encountered by system procedures. The MPM Reference 
Guide section/ The Multics Condition Mechanism, describes the 
signalling and handling of conditions in general. See also the 
MPM Reference Guide section/ Strategies for Handling Unusual 
Occurrences . 

This section lists the conditions signalled by system 
procedures/ and the default actions taken for each. The default 
on unit is invoked if no other user or system on unit has been 
established for the condition. The conditions are listed in 
alphabetical order by name. 

When present/ the parenthetical type designator at the 
right margin on the same line with the name indicates that the 
condition is either: 

1) defined by the PL/ I language; or 

2) due to a hardware fault or an error encountered while 
processing a hardware fault (indicating that a processor 
state description is available). 

Otherwise/ the condition is neither of these. 

Four items follow for each condition: 

1) cause is the reason the condition is signalled; 

2) default action is a brief description of the action taken 

by the default on unit; 

3) restrictions indicate when the user should not attempt 

to handle the condition and note when 
restarting after an occurrence of the 
condition is inappropriate; 

k) data structure is the PL/I declaration of the data that 

can be pointed to by info_ptr/ the fourth 
argument available to a condition handler. 
(See the MPM Subsystem Writers' Guide 
section/ Multics Condition Mechanism 
Arguments, for details.) Unless otherwise 
specified/ it is not generally useful for 
the handler to change the values of 
variables in the data structure. 
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jhs. PL/1 Condi tion Data structure 

Most of the PL/ I conditions have the data structure 
described below. Only the items associated with a particular 
instance of a condition are filled in. The relevant information 
should be obtained from the PL/I defined ondata functions. Users 
should not refer to this structure (beyond the header) since it 
is primarily an implementation vehicle for the ondata functions. 

For brevity, the data structure item of PL/I conditions that 
use this data structure is listed as "the standard PL/I data 
structure" . 



declare 1 info aligned, 

2 length fixed bin, 
2 version fixed bin, 
2 action_flags aligned, 

3 cant_restart bit(l), 

3 defaul t_restart bit(l), 

3 pad bit(34), 
2 info_string char(256) var, 
2 status__code fixed bin(35), 
2 id char(8) init ("pi iocond") , 
2 content__f lags aligned, 
(3 vlsw, 

3 oncode_sw, 

3 onfile__sw, 

3 file_ptr_sw, 

3 onsource_sw, 

3 onchar_sw, 

3 onkey_sw, 

3 onfield_sw) bit(l) unaligned, 
2 oncode fixed bin(35), 
2 onfile char(32) aligned, 
2 file ptr ptr, 
2 onsource char(256) var, 
2 oncharindex fixed bin, 
2 onkey_onf ield char(256) var; 



1) length 

2) version 

3) action_flags 
cant_res tart 



is the length in words of this structure, 
is the version number of this structure. 

indicates appropriate behavior for a handler: 

if "l"b, a handler should never attempt to 
return to the signaling procedure. 
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def aul t_restart if "l"b, the computation can resume with no 

further action on the handler's part except a 
return. 



i nf o__str i ng 
status_code 

id 

vlsw 

oncode_sw 

onf i 1 e__sw 

f i le_j5tr_sw 

onsource_sw 

onchar_sw 

onkey_sw 

onf i el d__sw 

oncode 

onf i le 
f i le_ptr 

onsource 



is a printable message about the condition. 

is the status code, if any, that caused the 
condition to be signalled. 

identifies this structure as belonging to a 
PL/I condition. 

if M l"b, indicates that the condition was 
raised by a version 1 PL/ I procedure. 



if "r'b, indicates that 
contains a valid oncode. 



the 



st ructure 



if "l"b, indicates that a file name has been 
copied into the structure. 

if M l"b, indicates that there is a file 
associated with this condition. 



if "l"b, indicates that there is 
onsource string for this condition. 

if "l"b, indicates that there is 
onchar index in this structure. 

if "l"b, indicates that there is 
onkey string in this structure. 

if "l"b, indicates that there is 
onfield string in this structure. 



val i d 
val i d 
val i d 
val i d 



is the condition's oncode if oncode_sw = 
M l"b. 

is the onfile string if onfile_sw = "l"b; 

is a pointer to a file value if file_ptr_sw = 
n l"b. 

is the onsource string if onsource_sw = M l"b. 
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19) oncharindex is character offset in onsource of the 

offending character if onchar__sw ■ ,f l"b. 

20) onkey_onf iel d is the onkey string if onkey_sw = n l"b and is 

the onfield string if onfield_sw = "l M b. 

Shorthand Notation 

One default action description occurs frequently. For 
brevity, it is listed as 

"prints a message and returns to command level" 

to mean 

"an error message is printed on the stream "error_output", 
and the user is placed at command level with a higher level 
stack frame than before the condition was signalled". 

Thus his stack is intact and the history of the error is 
preserved. The user can hold the stack for further debugging 
activities, or he can release it. (See the MPM write-ups for the 
debug, hold, release and start commands.) 

System Condi tiQns 



act i ve_f unct i on__er ror 

Cause: the user incorrectly used an active function in a 
command line. The procedure act i ve_f nc_err_ signals this 
condition. See the MPM Reference Guide section, The Command 
Language. 

Default action: prints a message and returns to command 
level . 

Restrictions: none. 
Data structure: 

declare 1 act i ve_f unct i on_error_i nfo aligned, 

2 length fixed bin, 

2 version fixed bin, 

2 act ion__f lags aligned, 

3 cant_restart bit(l) unaligned, 
3 def aul t_restart bit(l) unaligned, 
3 pad bit(3U) unaligned. 
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2 info_string char(256) var, 

2 status_code fixed bin(35), 

2 name_ptr ptr, 

2 narne_lth fixed bin, 

2 errmsg_ptr ptr, 

2 errmsg_lth fixed bin, 

2 max_er rmsg_J th fixed bin, 

2 print__sw bit(l); 



1) length is the length is words of this 

structure, 

2) version is the version number of this structure. 

3) action_flags indicates appropriate behavior for a 

handler: 

cant_restart if "l"b, a handler should never attempt 

to return to the signalling procedure. 

def aul t_restart if "l"b, the computation can resume with 

no further action on the handler's part 
except a return. 



pad is currently ignored. 

k) info_string is a printable message about the 

condi t ion. 



5) status_code 

6) name_ptr 

7) name_lth 

8) errmsg_ptr 

9) errmsg_lth 



is the status code being reported by 
a c t i v e__f n c_e r r_ . 

is a pointer to a character string 
containing the name of the procedure 
which called act i ve_f nc_err_. 

is the length of the name of the 
procedure which called act i ve_f nc_err_. 

is a pointer to a character string 
containing the error message prepared by 
act i ve_fnc_er r_. A handler might wish 
to alter that message. 

is the significant length of the error 
message prepared by act i ve_f nc_er r_. 
This datum can be changed by the 



(c) Copyright, 1973, Massachusetts Institute of Technology 

and Honeywell Information Systems Inc. 




System Conditions 

Handling Unusual Occurrences 

Page 6 



MULT ICS PROGRAMMERS 1 MANUAL 



handler. 

10) max_er rmsg^l th is the size of the character string 

containing the error message prepared by 
act i ve__f nc__err_. 

11) print_sw if "l"b, the error message will be 

printed by act i ve_f nc__err_ if and when 
the handler returns control to it. This 
datum can be changed by the handler. 



alrm (hardware) 

Cause: a real-time alarm occurred a specified length of 
time after a call by the user to t imer__manager_$alarm_cal 1 
(to set the alarm). See the MPM write-up for 
time r_manager_. 

Default action: the handler looks up the alarm that is 
expected at the time this one occurred, and calls the 
appropriate user-specified procedure. When (if) this 
procedure returns/ the user's process is returned to the 
point at which it was interrupted. 

Restrictions: the user should not attempt to handle this 
condi t ion. 

Data structure: none. 

Note: any__other handlers should pass this on. 



area (PL/I) 

Cause: the user attempted to either 1) allocate storage in 
an area that had insufficient space remaining to generate 
the storage needed; or 2) assign one area to another, and 
the second had insufficient space to hold the storage 
allocated in the first. 

Default action: prints a message on the "error_output n 
stream and signals the error condition. Upon a normal 
return, the attempted allocation is retried in case the user 
has freed some storage from an area in the interim. 

Restrictions: none. 
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Data structure: none. 



bad__outward_cai 1 (hardware) 

Cause: the user attempted to make an illegal call to an 
outer ring. 

Default action: prints a message and returns to command 
level . 

Restrictions: none. 
Data structure: none. 



comma nd__er ror 

Cause: the user incorrectly used a command (such as giving 
it bad arguments), or a command encountered a situation that 
prevented it from completing its operation normally. The 
procedure com_err_ signals this condition. 

Default action: returns to com_er r_, which then prints a 
formatted message on the stream "error_ output" • Other more 
sophisticated handlers could reformat the error message to 
the individual user's taste, or take some special action 
depending on the particular condition in question. 

Restrictions: none. 

Data structure: 

declare 1 command__er ror_i nfo aligned, 

2 length fixed bin, 

2 version fixed bin init(2), 

2 act ion__f 1 ags aligned, 

3 cant_restart bit(l) unaligned, 
3 def aul t__restart bit(l) unaligned, 
3 pad bit(34) unaligned, 

2 info_string char(256) var, 

2 status_code fixed bin(35), 

2 name_ptr ptr, 

2 name_lth fixed bin, 

2 errmess__ptr ptr, 

2 errmess__lth fixed bin, 

2 max_errmess_l th fixed bin init(256), 
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2 print_sw bit(l) ini t("l"b); 



1) length 

2) version 

3) act ion_f lags 

cant__restart 



is the length 
structure. 



i n 



words of 



this 



is the version number of this structure. 

indicates appropriate behavior for a 
handler: 

if "l"b, a handler should never attempt 
to return to the signalling procedure. 



def aul t_restart if "l"b, the computation can resume with 

no further action on the handler's part 
except a return. 



pad 

k) info_string 

5) status_code 

6) name_ptr 

7) name_J th 

8) errmess_ptr 

9) errmess_lth 



is currently ignored. 

is a printable message 
condi t ion. 



about the 



is the status code being reported by 
com_er r_. 

is a pointer to a character string 
containing the name of the procedure 
which called com__err_. 

is the length of the name of the 
procedure which called com_err_. 

is a pointer to a character string 
containing the error message prepared by 
com_err_. A handler might wish to alter 
that message. 

is the significant length of the error 
message prepared by com_err__. This 
datum can be changed by the handler. 



10) max_er rmess_J th is the size of the character string 

containing the error message prepared by 
com err . 



11) print_sw 



if "l"b, the error message is printed by 
com_err_. This datum can be set by the 
handl er . 
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comma n d_q ue r y_e r r o r 

Cause: the user specified a handler for the 
comma n deques t i on condition that did not return a "yes" or 
"no" answer when the data structure element indicated that a 
"yes" or "no" answer was required. The procedure 
comma nd_query__ signals this condition. 

Default action: prints a message and returns to command 
1 eve 1 . 

Restrictions: none. 
Data structure: none. 



command_quest i on 

Cause: a command is asking a question of the user. The 
procedure command_query_ signals this condition. 

Default action: returns to command_query__, which then 
prints the question on the stream "user_output" . Other more 
sophisticated handlers could supply a preset answer, modify 
the question or suppress its printing. See the data 
structure below for details. 

Restrictions: none. 

Data structure: 

declare 1 command_ques t i on_i nf o, 

2 length fixed bin, 

2 version fixed bin init(2) / 

2 act i on__f 1 ags al igned, 

3 cant_restart bit(l) unaligned, 
3 def aul t__restart bit(l) unaligned, 
3 pad bit(3U) unaligned, 

2 info__string char(256) var, 

2 status_code fixed bin(35), 

2 query_code fixed bin(35), 

2 question_sw bit(l) init ("l"b) unaligned, 

2 yes_or_no_sw bit(l) unaligned, 

2 preset_sw bit(l) init("0"b) unaligned, 

2 answer_sw bit(l) init("l"b) unaligned, 

2 name_ptr ptr, 

2 name_l th fixed bin, 
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2 question_ptr ptr, 

2 question_1th fixed bin, 

2 max__quest ion_l th fixed bin, 

2 answer_ptr ptr, 

2 answer_lth fixed bin, 

2 max_answer_l th fixed bin; 



1) length 

2) version 

3) act ion_f lags 
cant_restart 
def aul t__restart 

pad 

h) info_string 

5) status__code 

6 ) pad 

7) quest ion_sw 

8 ) ye s_p r_no_s w 



9) preset_sw 



is the length 
structure. 



i n 



is the version 
structure. 



words 
number 



of 
of 



this 
this 



indicates appropriate behavior for a 
handl er : 

if "1%, a handler should never attempt 
to return to the signalling procedure. 

if "l"b, the computation can resume 
with no further action on the handler's 
part except a return. 



is currently ignored. 

is a printable message 
condi t ion. 



about the 
the 



is the status code that prompted 
call to command_query_. 



is currently ignored. (A value of zero 
is always passed to the handler.) 

if "l"b, command_query__ prints the 
question. This datum can be set by the 
handler. 

if "1%, indicates that comma nd__query_ 
expects the preset answer (if any) 
returned by the handler to be either 
"yes" or "no". In this case, if the 

string, 

the 



handler returns any other 
comma nd_query_ signals 
command_query__error condition. 



if "l"b, the handler is returning in 
the character string pointed to by 
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10) answer_sw 



11) name__ptr 



12) namelth 



13) quest i on__ptr 



HO question_lth 



answer_ptr a preset 
command_query__. In 
comma nd_query__ returns 



answer to 
that case, 
the preset 

rl <-> a. e- 



answer to its caller. That 
not attempt to obtain an interactive 
response by reading from the stream 
fl user_i nput" . This datum can be 
changed by the handler. 

if ,, l"b / comma nd_query_ prints the 
preset answer (if any). This datum can 
be changed by the handler. 

is a pointer to a character string 
containing the name of the procedure 
which called comma nd_query_. 

is the length of the name pointed to by 
name__ptr . 

is a pointer to a character string 
containing the question prepared by 
command__query__. A handler might wish 
to alter that question. 



is the significant 
question pointed to 
This datum can be 
handl er . 



length of the 
by quest ion_ptr. 
changed by the 



15) max__quest ion_l th 



16) answer_ptr 



17) answer_Jth 



18) max_answer_l th 



is the size of the character string 
pointed to by quest ion_ptr . 

is a pointer to a character string that 
can be used by the handler to return a 
preset answer. 

is the significant length of the preset 
answer pointed to by answer_ptr. This 
datum can be changed by the handler. 

is the size of the character string 
pointed to by answer_ptr. 



Notes: a preset answer 
read from the stream 
trailing blanks and the 



is treated exactly as if it had been 
"user_i nput"; that is, leading and 
terminal new line character (if any) 
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are removed. 

If the yes_or__no_sw is on and a preset answer is returned 
that is not "yes" or "no"/ comma nd_query__ signals the 
condition commancL.query__error . 



conversion (PL/ I) 

Cause: a PL/ I conversion or runtime-I/O routine attempted 
an illegal conversion from character string representation 
to some other representation. Possible illegal conversions 
are a character other than 0 or 1 being converted to bit 
string, and non-numeric characters where only numeric 
characters are permitted in a conversion to arithmetic data. 

Default action: prints a message on the "er ror_output M 
stream and signals the error condition. Upon a normal 
return, the conversion is attempted again, using the value 
of the PL/I onsource pseudovar i abl e as the input character 
string. 

Restrictions: none. 

Data structure: the standard PL/I data structure. 

Note: the user can establish a handler that uses the onchar 
and onsource builtin functions to alter the invalid 
character string. 



cput (hardware) 

Cause: a CPU-time interrupt occurred after a user-specified 
amount of CPU time had passed following a call to 
t imer_manager_$cpu_cal 1 . (See the MPM write-up for 
t i me r_manage r_. ) 

Default action: the handler looks up the CPU time interrupt 
that is expected at this time and calls the appropriate 
user-specified procedure. When (if) this procedure returns, 
the process is returned to the point at which it was 
interrupted. 

Restrictions: the user should not attempt to handle this 
condi t ion. 
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Data structure: 



none. 



Note: any_other handlers should pass this on. 



cross_r i ng_transf er 



(hardware ) 



Cause: the user attempted to cross ring boundaries using a 
transfer instruction. A CALL or RTCD instruction must be 
used to cross ring boundaries. 

Default action: prints a message and returns to command 
level . 

Restrictions: none. 
Data structure: none. 



derail (hardware) 

Cause: the user attempted to execute a derail instruction 
on the 6180. 

Default action: prints a message and returns to command 
1 evel . 

Restrictions: usually none. However/ some subsystems 
(e.g./ Dartmouth) use it for special purposes* When 
operating within such subsystems, the user should not 
attempt to handle the condition. 

Data Structure: none. 



Cause: a PL/ I get or read statement attempted to read past 
the end of data on the file f. 

Default action: prints a message on the "error_outpu t" 
stream and signals the error condition. Upon return from 
any handler, control passes to the PL/ I statement following 
the statement in which the condition was raised. 

Restrictions: none. 
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Data structure: the standard PL/I data structure. 



endpage (f) (PL/I) 

Cause: PL/I inserted the last "new line" character of the 
current page into the output stream of the file f. I.e., if 
page_size is the number of lines normally placed on a page, 
then the (page_s i ze) th "new line" character is the last one. 

Default action: begins the next page on the file f and 
returns . 

Restrictions: none. 

Data structure: the standard PL/I data structure. 

Note: the handler can begin a new page via a PL/ I statement 
of the form 

put file (f) page ... (... "title"...) 

or can simply return, permitting the number of lines on the 
current page to exceed the number normally occurring. 



error (PL/I) 

Cause: some other (more specific) PL/I condition occurred, 
and its handler signalled the error condition. 
Alternatively, some PL/I runtime subroutine (e.g., one in 
the mathematical library) enountered one of a variety of 
errors . 

Default action: prints a message and returns to command 
1 evel . 

Restrictions: if the error condition is not merely an echo 
of another PL/ 1 condition, then restarting (i.e., returning 
control to the signaller) is usually undefined. 

Restarting from other PL/I conditions is discussed under the 
individual conditions. 

Data structure: the standard PL/I data structure. 
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f aul t__tag_l/ fault_tag_3 (hardware) 

Cause: the user attempted an indirect reference through a 
word pair containing either a fault tag 1 or a fault tag 3 
modi f ier. 

Default action: prints a message and returns to command 
level . 

Restrictions: none. 
Data structure: none. 



finish 

Cause: the user's process is being terminated by a logout 
(either voluntary or involuntary) or by a new_j>roc command. 

Default action: closes all open files and returns. 

Restrictions: if the process is terminating because of a 
bump or resource limit stop/ there is only a small grace 
period before the process is actually killed. If a 
user-supplied handler does not return/ the process continues 
to run but in some cases a subsequent process termination is 
fatal . 

Data structure: none. 

Note: any__other handles should pass this on. 



f ixedoverf low (hardware) 

Cause: the result of a binary fixed-point operation 

exceeded 71 bits, or the result of a decimal fixed-point 
operation exceeded 63 digits. 

Default action: prints a message on the "error_output" 
stream and signals the error condition. 

Restrictions: a return to the point where the signal 

occurred is prohibited since continued execution from this 
point is undefined. 
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Data structure: none. 



gate_error 



Cause: the user attempted an inward wall crossing through a 
gate segment with the wrong number of arguments. 

Default action: prints a message and returns to command 
level . 

Restrictions: none. 
Data structure: none. 



i 1 legal_modi f i er (hardware) 

Cause: an illegal modifier appeared on an indirect word. 

Default action: prints a message and returns to command 
1 evel . 

Restrictions: none. 
Data structure: none. 

Note: this error caused the op__not_compl ete condition to be 
signalled on the 6^5. 



i 1 1 egal_opcode 



(hardware) 



Cause: the user attempted to execute an illegal operation 
code. In a machine language program this could be a simple 
programmer error. It could also be a compiler error or a 
hardware error. 

Default action: prints a message and returns to command 
level . 

Restrictions: none. 
Data structure: none. 



i 1 i egal__procedure 



(hardware) 
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Cause: the user attempted to execute a privileged 
instruction/ or tried to execute an instruction in an 
illegal way. 

Default action: prints a message and returns to command 
level . 

Restrictions: none. 
Data structure: none. 



i 1 1 ega 1 __r i ng_o r de r 



(hardware) 



Cause: ring brackets on a segment are in the wrong order; 
i.e./ not in ascending order. 

Default action: prints a message and returns to command 
level . 

Restrictions: none. 
Data structure: none. 

i 1 legal_return 

Cause: an attempt was made to restore the control unit with 
illegal information. 

Default action: prints a message and returns to command 
1 eve 1 . 

Restrictions: none. 
Data structure: none. 



i o_error 



Cause: an I/O procedure which does not return an I/O system 
status code received such a code from an inferior I/O 
procedure. The first procedure (e.g., ioa_) reflects the 
error by signalling this condition. 

Default action: prints a message and returns to command 
level . 
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Restrictions: none. 
Data structure: 

declare 1 i o_error_i nfo aligned, 

2 length fixed bin, 

2 version fixed bin init (0), 

2 act ion_f 1 ags aligned, 

3 cant_restart bit(l) unaligned, 
3 def aul t__restart bit(l) unaligned, 
3 pad bit(3U) unaligned, 

2 info_str ing__char(256) var, 

2 stream char(32), 

2 status bit(72); 



1) length 

2) version 

3) act ion_f lags 

cant restart 



is the length 
structure. 



in words of this 



is always 0 in this case. 

indicates appropriate behavior for a 
handl er : 

if "l n b, a handler should never attempt 
to return to the signalling procedure. 



def aul t_restart if "l"b, the computation can resume with 

no further action on the handler's part 
except a return. 



pad 

k) info_string 

5) status_code 

6) stream 

7) status 



is currently ignored. 

is a printable message 
condi t ion. 



about 



the 



is the unexpected status code received 
by an I/O procedure. 

is the name of the stream on which the 
I/O operation was performed. 

is the I/O system status code describing 
the error. 



toa__er ror 
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Cause: the user called an ioa_ entry with illegal 
arguments. The possible incorrect calls are: 

1) failed to provide a stream name for 

i oa_$ i oa_s t ream 

I oa_$ i oa_s t ream_nn 1 

2) failed to provide a correct character string descriptor 
for 

i oa__$ rs 

ioa__$rsnnl 

ioa__$rsnpnnl 

Default action: prints a message and returns to command 
1 evel . 

Restrictions: none. 
Data structure: none. 



key (f) (PL/I) 

Cause: the user attempted to specify an invalid key in a 
PL/i record-l/0 statement on the file f. Two possible 
illegal uses are 1) a keyed search failed to find the 
designated key; and 2) on output, the designated key 
duplicates a pre-existing key. 

Default action: prints a message on the "error_output" 
stream and signals the error condition. Upon return from 
any handler, control passes to the PL/ I statement following 
the statement in which the condition was raised. 

Restrictions: none. 

Data structure: the standard PL/I data structure. 

Note: the handler can obtain the value of the invalid key 
by use of the onkey builtin function. The invalid key 
cannot, however, be corrected in the handler. 



1 i nkage_error (hardware) 

Cause: the user's process encountered a fault tag 2 in a 
word pair. It then attempted to reference the external 
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entry specified by the word pair and failed because either 
the segment was not found or the entry point did not exist 
in that segment. 

Default action: prints a message and returns to command 
1 evel . 

Restrictions: none. 
Data structure: none. 

lockup (hardware) 



Cause: a pending interrupt has not been allowed for too 
long. This can be caused by a looping instruction pair, an 
infinite indirection chain, or a bar mode interrupt inhibit 
bit on for too long. 

Default action: prints a message and returns to command 
1 evel . 

Restrictions: none. 
Data structure: none. 

Note: this condition was signalled only because of an 
infinite indirection chain on the 645. 



loop_wa i t_error 

Cause: a procedure operating in or calling into the 
Hardcore Ring called pxss$ 1 oop_wa i t with bad or illegal 
arguments . 

Default action: prints a message and returns to command 
level, after leaving the Hardcore Ring (i.e., the default 
handler operates only in outer rings). 

Restrictions: the user should not attempt to handle this 
condi t ion. 

Data structure: none. 
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message__segment_error 

Cause: an absentee queue was found by the message segment 
facilty to be in an inconsistent state/ or a crawlout from 
the Administrative Ring occurred in the message segment 
faci 1 i ty. 

Default action: prints a message and returns to command 
level . 

Restrictions: since the message segment facility is used 
only for system services such as absentee queues, the user 
should not attempt to handle this condition. 

Data structure: none. 



mmel, mme2, mme3, mme^ (hardware) 

Cause: the user attempted to execute the 6180 instruction 
mmea, where a is 1, 2, 3 or Ij. 

Default action: prints a message and returns to command 
level . 

Restrictions: none. 
Data structure: none. 

Note: the debug command uses the mme2 condition to 
implement breakpoints. This the user will encounter 
problems if he attempts to set breakpoints in a program that 
handles the mme2 condition. 



name (f) (PL/ I) 

Cause: an invalid identifier occurred in a PL/I get data 
statement on the file f. 

Default action: prints a message on the stream 
"error__output" and signals the error condition. Upon return 
from any handler, the invalid identifier and its associated 
value field are skipped. 

Restrictions: none. 
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Data structure: the standard PL/I data structure. 

no_execute__ permi ssion (hardware) 

Cause: the user attempted to execute a segment to which he 
did not have execute permission. 

Default action: prints a message and returns to command 
1 evel . 

Restrictions: none. 
Data structure: none. 



no__read_permi ss ion (hardware) 

Cause: the user attempted to read from a segment to which 
he did not have read permission. 

Default action: prints a message and returns to command 
level . 

Restrictions: none. 
Data structure: none. 

no_wr i te_permi ss ion (hardware) 

Cause: the user attempted to write into a segment to which 
he did not have write permission. 

Default action: prints a message and returns to command 
level . 

Restrictions: none. 
Data structure: none. 

not_a__gate (hardware) 

Cause: the user attempted to call into a gate segment 
beyond its call limiter; i.e./ beyond the upper bound of the 
transfer vector in a gate. 
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Default action: prints a message and returns to command 
level . 

Restrictions: none. 
Data structure: none. 



Cause: the user attempted to call a segment from a ring not 
within the segment's call bracket. 

Default action: prints a message and returns to command 
1 evel . 

Restrictions: none. 
Data structure: none. 

not_i n__execute__b racket (hardware ) 

Cause: the user attempted to execute a segment from a ring 
not within the segment's execute bracket. 

Default action: prints a message and returns to command 
1 evel . 

Restrictions: none. 
Data structure: none. 

not_in__read_bracket (hardware) 

Cause: the user attempted to read a segment from a ring not 
within the segment's read bracket. 

Default action: prints a message and returns to command 
1 evel . 

Restrictions: none. 
Data structure: none. 



not_in_cal l_b racket 



(hardware) 
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not_i n_wr i te_bracket 



(hardware) 



Cause: the user attempted to write into a segment from a 
ring not within the segment's write bracket. 

Default action: prints a message and returns to command 
1 evel . 

Restrictions: none. 
Data structure: none. 



op_not_compl ete (hardware) 

Cause: 1) the processor failed to access memory v/ithin 
approximately 2 ms after its previous memory access. 

Default action: prints a message and returns to command 
1 evel . 

Restrictions: none. 
Data structure: none. 

Note: upon return to the signalling procedure, the 
processor attempts to continue execution at the point where 
the op not complete was detected. The processor usually 
continues execution correctly but the machine state might be 
such that continued execution is at the user's risk. 



out_pf__bounds (hardware) 

Cause: the user attempted to refer to a location beyond the 
end of the segment specified. 

Default action: prints a message and returns to command 
1 evel . 

Restrictions: none. 
Data structure: none. 
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overflow (hardware) 

Cause: the result of a floating-point computation had an 
exponent exceeding 127. 

Default action: prints a message on the "er ror__outpu t" 
stream and signals the error condition. 

Restrictions: returning to the point where the signal 
occurred is not allowed since continued execution from this 
point is undefined. 

Data structure: none. 



page__f aul t__error (hardware) 

Cause: the normal paging mechanism of the Multics 
supervisor could not bring a referenced page into memory 
because the storage system device containing the page could 
not be read due to a hardware error that could not be 
corrected by the error condition mechanism. 

Default action: prints a message and returns to command 
level . 

Restrictions: none. 
Data structure: none. 

parity (hardware) 

Cause: the process attempted to refer to a location in 
memory that has incorrect parity, or to use a RCCL (read 
clock) instruction on a memory port that does not have a 
clock. The first is a hardware error; the second is a 
hardware error or incorrect hardware configuration. 

Default action: prints a message and returns to command 
1 evel . 

Restrictions: none. 
Data structure: none. 



(c) Copyright, 1973, Massachusetts Institute of Technology 

and Honeywell Information Systems Inc. 




System Conditions 

Handling Unusual Occurrences 

Page 26 



MULT ICS PROGRAMMERS' MANUAL 



program_i nterrupt 

Cause: the user issued the program_i nterrupt (pi) command 
for the express purpose of signalling this condition. The 
condition is used by several commands to return to their 
internal request level (waiting for the next request) after 
the previous request has been aborted by the user pressing 
his interrupt (quit) button. 

Default action: prints a message and returns to command 
1 evel . 

Restrictions: none. 
Data structure: none. 

Note: any_other handlers should pass this on. 



qui t 

Cause: an interactive user has requested a quit; for 
example, by pressing the quit button on his terminal. 

Default action: prints "QUIT" on the terminal, aborts any 

pending terminal I/O activity, reverts the standard I/O 

attachments to their default settings, and establishes a new 
command level, saving the current stack history. 

Restrictions: none. But, in general, the user's programs 
should not handle the quit condition since this condition is 
normally intended to bring the process back to command 
level. In addition, a program with a quit handler is more 
difficult to debug since a bug in the quit handler might 
make it impossible to interrupt the execution of the 
program. Certain subsystems can, for various reasons, still 
choose to make use of the quit condition; but most programs 
should, instead, use the program__i nterrupt condition as 
described eariler in this section. 

Data structure: none. 

Notes: The standard I/O attachments are described under 

Usage in the MPM Reference Guide section Use of the Input 
and Output System. any_other handlers should pass this on. 
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record (f) (PL/I) 

Cause: a PL/1 read statement on the Hie f read a record of 
a size different from the variable provided to receive it. 

Default action: prints a message on the "er ror_ou tpu t" 
stream and signals the error condition. Upon return from 
any handler data is copied from the record to the variable 
by a simple bit-string copy as though both were the length 
of the shorter. 

Restrictions: none. 

Data structure: the standard PL/1 data structure. 



record__quota_overf low (hardware) 

Cause: the user attempted to increase the number of records 
taken up by the segments inferior to a directory to a number 
greater than the secondary storage quota for that directory. 

Default action: prints a message and returns to command 
1 evel . 

Restrictions: none. 
Data structure: none. 



seg_f aul t_error (hardware) 

Cause: the user attempted to use a pointer with an illegal 
segment number. This situation arises when 1) a segment was 
deleted or terminated after the pointer was initialized; 2) 
the pointer was not initialized in the current process; or 
3) the user had null access to the segment. 

Default action: prints a message and returns to command 
1 evel . 

Restrictions: none. 
Data structure: none. 
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s imf aul t_nnnnnn (hardware) 

Cause: the user attempted to use a null pointer; i.e., a 
pointer w? th a segment number of -1 (2's complement) and an 
offset of nnnnnn. The offset is mapped into the 6-character 
string nnnnnn that makes up part of the condition name. 

Default action: prints a message and returns to command 
1 evel . 

Restrictions: none. 
Data structure: none. 

Note: If a user references through a null pointer with no 
offset modification/ the condition simf aul t_000001 is 
s i gna 1 1 ed . 

size (PL/I) 

Cause: some value was converted to fixed-point with a loss 
of one or more high-order bits or digits. 

Default action: prints a message on the "er ror_outpu t" 
stream and signals the error condition. 

Restrictions: returning control to the point where the 
signal occurred is not allowed since the results of 
continued execution are undefined. 

Data structure: the standard PL/I data structure. 

stack 

Cause: The user attempted to make a reference within the 
last four pages of the stack. 

Default action: prints a message and returns to command 
1 evel . 

Restrictions: none. 
Data structure: none. 

Note: any_ other handlers should pass this on. 
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storage (PL/1) 

Cause: the PL/I "system storage" has insufficient space for 
an attempted allocation. 

Default action: prints a message on the "er ror_output" 
stream and signals the error condition. Upon a normal 
return the allocation is retried. 

Restrictions: none. 

Data structure: none. 



store (hardware) 

Cause: an out_of_bounds error occurred while operating in 
bar mode/ or the user referred to a non-existant memory 
(e.g., by attempting to read a clock on the memory). 

Default action: prints a message and returns to command 
1 evel . 

Restrictions: none. 

Data structure: none. 

stringrange (PL/I) 

Cause: the substr. pseudovar i abl e. or builtin. function 
specified a substring that is not in fact contained in the 
string specified. 

Default action: prints a message on the "error_outpu t" 
stream and signals the error condition. 

Restrictions: returning control to the point where the 
signal occurred is not allowed since the results of 
continued execution are undefined. 

Data structure: the standard PL/ I data structure. 
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stringsize (PL/I) 

Cause: a string value was assigned to a string variable 
shorter than the value. 

Default action: returns to the point where the condition 
was signalled/ causing a truncated copy of the string value 
to be assigned to the string variable. 

Restrictions: none. 

Data structure: the standard PL/1 data structure. 



subscriptrange (PL/I) 

Cause: the value of a subscript lies outside the range of 
values declared for the bounds of the dimension to which it 
appl i es . 

Default action: prints a message on the ,, error_output" 
stream and signals the error condition. 

Restrictions: returning control to the point where the 
signal occurred is not allowed since the results of 
continued execution are undefined. 

Data structure: the standard PL/1 data structure. 



t i mer_manager_er r 

Cause: the event channel on which timer_manager_ would go 
to sleep could not be created, or i pc_ $block returned a 
non-zero status code when t imer_manager_ went to sleep on 
it. Either internal static storage for timer_ manager^ has 
been destroyed or the system is about to crash. This 
condition is also signalled if t imer_manager_ is called in a 
ring other than that in which the process was created, 
indicating a programming error in the calling procedure. 

Default action: prints a message and returns to command 
1 evel . 

Restrictions: the user should only attempt to handle this 
in a handler for otherwise unclaimed signals. 

Data structure: none. 
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transmit (f) 



(PL/ I) 



Cause; a value was incorrectly transmitted between storage 
and the data set corresponding to the file f. In the case 
of list-directed input, the condition is signalled after 
each assignment by the get statement of a value that might 
have been in error due to the bad input line. 

Default action: prints a message on the "error_output" 
stream and signals the error condition. Upon return from 
any handler, the program continues from the point of 
detection as though the transmission had been correct. 

Restrictions: none. 

Data structure: the standard PL/I data structure. 



truncation (hardware) 

Cause: the user executed an extended instruction set 
instruction to move string data with the truncation bit set, 
and the target string was not large enough to contain the 
source string, or bit strings were being combined to the 
left or right (also EIS instructions) and there was not 
enough room to hold the combined string. 

Default action: prints a message and return to command 
1 evel . 

Restrictions: none. 
Data structure: none. 



undef inedf i le (f) (PL/i) 
Cause: an attempt to open the PL/I file f failed. 

Default action: prints a message on the "error_output l! 
stream and signals the error condition. 

Restrictions: none. 

Data structure: the standard PL/I data structure. 
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underflow 



( hardware) 



Cause: the result of a floating-point computation had an 
exponent less than -128. 

Default action: prints a message on the "error_output n 
stream and returns. 

Restrictions: none. 

Data structure: none. 

Note: before the underflow condition is signalled the 
floating-point value in question is set to zero. 



unwinder_error 



Cause: the user attempted to perform a non-local transfer 
to an invalid location. 

Default action: prints a message and returns to command 
1 evel . 

Restrictions: none. 

Data structure: 

declare i nval i d_label label; 

1) i nval i d_l abel is the invalid label to which this transfer 
v was attempted. 



zerodivide (PL/I) 
Cause: the user attempted to divide by zero. 

Default handling: prints a message on the "error_output" 
stream and signals the error condition. 

Restrictions: returning control to the point where the 

signal occurred is not allowed since the results of 
continued execution are undefined. 

Data structure: the standard PL/I data structure. 
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IME UMITEP SERVICE SYSTEM 

A small set of Multics commands/ all of which are noted for 
their light resource usage., compose what is known as the Limited 
Service System (LSS). A user of the LSS is prevented by the 
system from using commands outside this set; in addition, his 
rate of CPU usage is tightly controlled. 

The LSS provides a way for a project to allow its members 
(or a subset of its members) access to computing services with a 
ceiling on the amount of money they will spend. For example, a 
professor could leave a terminal logged in all day, available to 
anyone in his class, and still be sure that only a fixed amount 
of money would be spent each day. 

To register an LSS user, the project administrator need only 
specify the LSS process overseer as that user's process overseer. 

The LSS is sufficiently modular that pieces of it (for 
instance, the piece that controls which commands are accessible) 
may be used in other subsystems. This means that subsystem 
writers can easily tailor their own limited systems with their 
own list of commands and/or governing parameters. Documentation 
of the subroutines necessary to do this are published in the MPM 
Subsystem Writers 1 Supplement (SWS). 

The following commands are currently allowed in the LSS: 

addname 
bas i c 

bas i c__system 

calc 

decam 

delete 

deletename 

edm 

help 

1 ist 

1 i stnames 
1 i stota 1 s 
logout 
pr i nt 

program__i nterrupt 

ready 

ready__of f 

ready_on 

rename 

start 
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JUL MMLTI C S D ARTMOUTH SYSTEM 

The Multics Dartmouth System provides a user with a closed 
subsystem which duplicates/ as closely as possible/ the Dartmouth 
Time-Sharing System (DTSS) as implemented at Dartmouth College, 
Both the command language and the access control mechanism have 
been simulated in Multics. The language processors and text 
editors of the subsystem are actual Dartmouth object modules, 
running in an environment which duplicates that of an HIS-635 
computer on which DTSS is normally run. 

Most commands operate identically to their counterparts at 
Dartmouth. Therefore, a user should refer to the documentation 
published by Dartmouth for detailed information. 



Multics Dartmouth System, a 
be set to the Dartmouth process 



i 



user s process 
overseer. This 



To use the 
overseer should 

operation must be done by the user's project administrator. To 
assure the security of the DTSS access control mechanism/ a 
Multics Dartmouth user will not be able to reference his 
Dartmouth directory/ except through the Multics Dartmouth System. 

Segments created under the Multics Dartmouth System are not 
compatible with other Multics segments. The end of the line 
convention under DTSS is the ASCII carriage return-new line. 
Under the regular Multics system, it is just "new line". 

The Multics Dartmouth System uses, unchanged, modules of the 
real DTSS. Errors detected in these modules should be referred 
to Dartmouth College. 

The following commands are supported with differences as 
noted: 

Command Notes 

BUI LD No change. 

BYE Executes the Multics logout command. 

CATALOG Only the options ALL, NFILES, and 

NHEADER are implemented. 

COMPILE No change. 

EDIT The EXPLAIN option is not implemented. 

GOODBYE is identical to BYE. 
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HELLO 

IGNORE 

LENGTH 

LIST 

NEW 

OLD 

RENAME 

REPLACE 

RUN 

SAVE 

SCRATCH 

SORT 

STRINGEDIT 
SYSTEM 

TEST 

TEXTEDIT 
TTY 

UNSAVE 
USERS 
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Executes the Multics command "logout hold". 
No change. 
No change. 
No change. 
No change. 

See Notes on passwords. 

If the syntax: 

<USERNUMBER> : <SEGMENTNAME> 

is used, the segment is assumed to be in 

>user_di r_di r>Proj ect>USERNUMBER>SEGMENTNAME. 

No change. 

See Notes on passwords. 
No change. 

See Notes on passwords. 
No change. 
No change. 
No change. 

The following systems are implemented: 

ALGOL FORTRAN 
BASIC LISP 
CHECKERS MIX 

Contact the system administrator to use the 
TEST command. 

No change. 

No change. 

See Notes on passwords. 

Prints the number of users currently on 
Mul t i cs . 
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XTEST See TEST. 

The following commands are not implemented; 

APPEND JOIN 

BACKGROUND KEYBOARD 

B I LLS L I NK 

DIRECT NFRIDEN 

EXPLAIN NPARITY 

FRIDEN PARITY 

FULLDUPLEX PUNCH 

HALFDUPLEX TAPE 

The following systems are not implemented: 

9 MAP GMAP 

ALGOL68 LAFFF 

DEBUGGER TRAC 
GEFORT 

Notes 

At Dartmouth/ a user may type: 

<C0MMAND> <NAME> / <PASSWORD> 

and DTSS will overstrike the password for security. This can be 
done at Dartmouth because the user terminates his command line 
with the ASCII character carriage return. Multics terminals 
normally terminate input lines with the "new line" character, 
thus precluding overstriking the line. Multics Dartmouth will 
accept this syntax but will not attempt to overstrike the line. 
However, both DTSS and Multics Dartmouth will accept the 
fol 1 owi ng syntax : 

<C0MMAND> <NAME>, 

Following this command/ the user is asked to enter a password. 
In this manner, the overstrlkes may be typed first and password 
security maintained. This second method is recommended to the 
user . 

The erase character on Multics Dartmouth is the number sign 
(#). The kill character is the commercial at sign (@). A quit 
condition may be signalled only by pressing the appropriate key 
on the terminal. (See the MPM Reference Guide section on the 
Protocol for Logging In for the quit button's marking on various 
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terminals.) The quit will be followed by the messages STOP and 
READY / at which point the monitor will again be listening for 
commands. 

Segment names in Multics Dartmouth should not contain the 
characters greater than (>) or less than (<). 

To enter a commercial at sign or a number sign into actual 
text/ the user should precede the character v/i th a backslash (\@ 
or \#). To enter a backslash into his actual text/ the user 
should type two backslashes ( \ N ) . (Note: the backslash character 
is a cent sign U) on a 2741/ 1050/ and Datel 30 terminal.) 

DTSS FORTRAN and LISP require all input to be in upper case 
letters. DTSS MIX maps all lower case letters into upper case. 
All other systems will accept upper and lower case letters 
i nterchangeabl y. 

A large percentage of the programs in the DTSS Program 
Library are available to users of the Multics Dartmouth System 
(and users of the basic and basic_run commands). These are 
programs written in BASIC and ALGOL and cover a large range of 
applications. See TM010 (described below) for full 

documentat i on . 

Documentation 

The Multics Dartmouth user should consult the following 
documents for detailed information: 



TM002 


Dartmouth EDIT 


TM003 


Dartmouth String Editor 


TMOOl* 


Text Users Manual 


TM006 


Double Precision in Dartmouth BASIC 


TM010 


User's Guide to the DTSS Program Library 


TM013 


MIX User's Reference Manual 


TM015 


System FORTRAN Reference Manual 


TM016 


Accurate Matrix Inversion in BASIC 


TM017 


LISP System Reference Manual for DTSS on 



GE635 
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TM021 Dartmouth ALGOL for the DTSS 

TM022 User f s Guide to DTSS 

BASIC, Fifth Edition 

The above documents are all published by the Dartmouth 
College Kiev/it Computation Center/ Hanover, New Hampshire. 

In addition, the user should reference the manual FORTRAN 
Language , published by General Electric for the Mark II 
Time-Sharing Service, manual number 802209. 



The current version of the Dartmouth System 
is a proprietary program of Dartmouth 
College. It has been made available to users 
of the M.l.T. Information Processing Center 
with the permission of Dartmouth College. 
The Dartmouth System may not be used at other 
computer installations without permission of 
Dartmouth College. 
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LIST OF NAMES WITH SPECIAL MEANINGS 



The following names are reserved for special purposes within 
Multics. The user should not use them with a different meaning. 
See also the following MPM Reference Guide sections for other 
names with special meanings: List of System Conditions and 
Default Handlers/ List of Names in the System Libraries, and 
Obsolete Procedures. 

Reserved jJSL $trQ?m Names 

By convention, the following I/O stream names are reserved. 
Those maintained by the standard environment are: 



user_i /o 

user__input 
user_putput 
er ror_output 



is the stream attached to the user's 
terminal or absentee input and output 
segments . 

is the stream attached to user__i/o and 
devoted expressly to read calls. 

is the stream attached to user_i/o and 
devoted expressly to write calls. 

is the stream attached to user_i/o and 
devoted expressly to write calls under 
error conditions. 



Those maintained by system commands or subroutines are 



e x e c_com_s t r e am_N 



f i 1 e_output_st ream_ 

graph ic__input 
graph ic_output 



is the stream attached by the exec_ com 
command using the attach command line. 
N is a unique sequence number assigned 
by exec_com. user_input is attached to 
this stream through the syn interface 
modul e. 

is the stream attached by the 
file_output command. user_output is 
attached to this stream through the syn 
interface module. 

is the stream used for graphics input, 
is the stream used for graphics output. 
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Reserved Segment Names 



By convention/ the following segment names are reserved. 
Those maintained in the home directory are: 



ma i 1 box 

s tar t__up. ec 

username. breaks 

username. con__msgs 



user name. memo 



username. motd 



username. prof i 1 e 



is the segment used by the mail command. 

is the exec_com invoked at the beginning 
of a process in the standard 
envi ronment . 

is the break segment used by the debug 
command. (username is the name derived 
from the login command.) 

is the segment used by the message 
facility (see the MPM write-up of the 
send_message command), (username is the 
name derived from the login command.) 

is the segment used by the memo command, 
(username is the name derived from the 
logi n command. ) 

is the segment used by the print_motd 
command. (username is the name derived 
from the print_motd command.) 

is the segment used by the abbrev 
command. (username is the name derived 
from the login command.) 



Those maintained in the process directory are: 

combined_J inkage_N. jk is the user's linkage segment for ring 

number N (1<=N<=7). jk is a two digit 

sequence number. This segment also 
contains internal static storage. 



drum_templ_ 1 
drum_temp2__ J 

kst 
pds 



is temporary storage used by aim, edm, 
and qedx. 

(Known Segment Table) is a Hardcore Ring 
data segment. 

(Process Data Segment) is a Hardcore 
Ring data segment. 
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Pit 



i s the 
Table. It 
through the 
the MPM 
user_i nfo__) 



user's Process Initialization 
should only be referenced 
subroutine user_info_ (see 
subroutine write-up for 



stack N 



system_f ree_N_ 



is the user's automatic storage area for 
ring number N (1<=N<=7). 

is the free storage area used by system 
commands for ring number N (K ss N< = 7). 



In general, users should not create segments whose names end 
in a trailing underscore (_) . >These names are reserved for 
system subroutines and may cause errors if they are in the user's 
search path. (See the MPM Reference Guide section/ The System 
Libraries and Search Rules.) 



Reserved Segment Name Suffixes 



Suffixes are used as in the following example: If one is 
creating a PL/ I source program to be named xyz f he would create a 
source language segment named xyz.pll. The PL/ I compiler/ by 
convention/ translates this segment/ producing the segment 
xyz.list/ containing a printable listing/ and the segment xyz, 
containing the object program. 

By convention/ the following segment name suffixes are 
reserved. The language translator source segment suffixes are: 



Language 
Translator 


Source 

Segment 


1 nclude 
Fi les 


PL/I compiler 


.pll 


. i ncl . pi 1 


FORTRAN compi ler 


.f ortran 


. i ncl . fortran 


ALM assembler 


.aim 


. i ncl . aim 


BASIC compiler 


.bas i c 




The listing segment 


suffix is: 





. 1 ist 



is the suffix on printed output listing 
segments produced by compilers/ the 
assembler, and the binder. 
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Other special suffixes are: 

.absin is the input segment suffix for an 

absentee process. 

.absout is the default output segment suffix for 

an absentee process. 

.apl is the suffix on the segment containing 

a saved workspace from the apl command. 

.archive is the suffix on the segment created by 

the archive command. 

.bind is the suffix on the input control 

segment for the binder. 

.dobj is the suffix on the output segment 

produced from the -compile control 
argument to the BASIC compiler. 

. ec is the suffix on the input segment to 

the exec__com command. 

.info is the suffix on a segment/ in 

>documentat ion> i nfo_segments, for use 
with the help command. 

.lisp is the suffix on the segment containing 

a saved environment from the lisp 
command. 

.ms is the suffix on an Administrative Ring 

message segment. 

.pt is the segment suffix for use with the 

peruse_text command. 

.runoff is the input segment suffix to the 

runoff command. 

.runout is the output segment suffix from the 

runoff command. 

Beseryed Object Segment Entry Point 

By convention, the following entry point definition in 
object segments is reserved. 
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symbol_table is the entry point definition which 

provides the address of the symbol table 
produced by the pll or fortran commands. 

Since this is a reserved entry point, no user-created 
program can use this name. A statement of the form 

symbol_tabl e : procedure... 

is illegal if it is the external procedure block. 
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1 . 1 ST QL NAMES _I_N IHE SYSTEM LIBRARIES 

The Multics system libraries/ >sys tem_l i brary_standard and 
>system_1 i brary_l, are described in the MPM Reference Guide 
section. The System Libraries and Search Rules* They contain 
the system commands and subroutines described in the MPM commands 
and MPM Subroutines sections. They also contain a number of 
other procedures not intended to be called directly by users, but 
included in these directories for various reasons. For example, 
old commands and subroutines that are being phased out (but are 
still available for an interim period) are left in these 
directories for the convenience of users who are converting to 
the replacements for these procedures. Similarly, if the name of 
a command or subroutine is changed, both names appear on the 
segment for a time, but users should call it only by the new 
name . 

In addition, the libraries contain entries that are internal 
interfaces of the Multics supervisor or command system, and are 
not intended to be called by the user. They are user-accessible 
primarily to ease the job of checkout of new system commands. 
User programs should not be coded with calls to these procedures 
as such calls would produce undesirable dependence one internal 
system organization or hardware configuration. This set of 
entries also represents a collection of names that should not be 
chosen for user-written subroutines, since if the user-written 
subroutine is lost, a call to it could wind up in the system 
subroutine of the same name. 

This write-up lists the names of those entries in 
>system__l i brary_standard and >sys tem_l i brary_l that the user 
should avoid. Several types of names are excluded from the list 
to make it more compact. The types of names excluded are: 

1) all system command names and their abbreviations. A list of 
command names can be found in the MPM Reference Guide table 
of contents; a list of abbreviations can be found in the MPM 
Reference Guide section. Command Name Abbreviations. 

2) all system subroutine names. A list of subroutine names can 
be found in the MPM Reference Guide table of contents. 

3) old versions of recently updated commands and subroutines 
(and possibly other procedures). These entry names have an 
additional component of "1" or "2"; e.g., an old version of 
the compare command might have the entry name compare. 1. 

h) all names ending in an underscore. System subroutine names 
are guaranteed to end in an underscore as described in the 
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MPM Reference Guide section. Constructing and Interpreting 
Names. Users can avoid conflicts by adopting some other 
convent ion. 



5) all names with more than one component. Users should not 

encounter conflicts with these names since procedure names 

should be of only one component. Typically/ mul t i -component 

names are used in situations where only the user's working 

directory is searched. 



6) all bound segments. The primary entry name of a bound 
segment in the system library always has the character 
string "bounds" as part of the first component of the name. 
Other entry names on the bound segment are unaffected (in 
this list) by the application of this rule. 



7) all separate linkage section segments. These segments are 
recognizable by the presence of "link" as the last component 
of the entry name. Each one has a corresponding text 
segment without the "link" component in its entry name. 

8) all unique names. These segments all have 15-character 
names with an exclamation point as the first character. 



active_al l_rings_data 
admi n_mode_ex i t 
asr 

backup_ut i 1 
changewdi r 
db_pr i nt 

delete_search_rul es 

d i sassembl e 

dsr 

f ile_util 
f scodedi nfo 
global 
i bm 

imf_state 
i nstal 1 

lot_ma i nta i ner 
lsrb 

name_tabl e 

ncp__test 

phd 

pom 

PP__of f 

PP«s i ze 

pr i nt_pdt 



add_search_rul es 
ame 

backup., load 
cal 1 er 

check_obj ect 

db_regs 

del etedi r 

di ssassemble 

file 

f 1 

gb 

gr__pr i nt 
i 1 oad 
i nd 

interpret_bi nd__map 
1 set_r i ng_J>i*ackets 
moveb 
nc 

netcal 1 

pi l_operators 

pp_mode 

PP_on 

pr i nt__obj ect_map 
pr i nthomedi r 



Q Copyright,- 1973,- Massachusetts Institute of Technology 

and Honeywell Information Systems Inc. 



MULT ICS PROGRAMMERS' MANUAL 




Names in The System Libraries 
Miscellaneous Reference Info 

Page 3 
11/1/73 



pr i ntwdi r 
pur 

reload 

retrieve 

sar 

setquota 
signal 
spe 
stacq 
sys_i nf o 

terminate__reference 
translator__ec__ec 
un?que_chars 
vlpa 



p r oj __u s a ge_j* e po r t 

read_convert 

rename_ns 

r i ng_zero_cleanup 

sethomedi r 

shd 

sit 

sq 

submi t__abs__request 
tdsm 

trans 1 a to r__abs i n_abs i n 
un ique_bi ts 
unwi nder 
vlpl l__abs 
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OBSOLETE PROCEDURE S 

The following procedures are obsolete subroutines or 
wr i tearounds which remain in the system so that early versions of 
system commands will continue to work. New programs should not 
be written to call any of these entry points. Old programs which 
use them should be modified to use the new procedure or technique 
i ndi cated. 



acm_ 

bi ndarchi ve 
bsys 

check_f s_errcode__ 



decode__obj ect_ 
defaul t„handl er_ 

del etedi r 
equal_ 

establ i sh_cl eanup_proc_ 
global 

hcs_$acl add 



(Use 
(Use 
(Use 
(Use 



) 



(Use 



hcs_$chname 

hcs_$f s_get_brackets 



n cs_$f s_search_get_wdi r 
hcs_$f s_search_set_wdi r 
hcs_$get_dbrs 
hcs_$get_usage__va 1 ues 
hcs_$proc_i nfo 

hcs_$set_t imer 

hcs_$usage_values 

ma k e_o b j _ma p_ 

moveb 

move_ 

ms_ 



(Use 
(Use 



ti mer_manager_ 
bind) 

basi c_sys tern) 
conver t__status_code__, 
documented in the MPM Subsystem 
Writers 1 Guide) 
obj ect_i nfo_) 
(Establish on unit for any__other 

condi t i on ) 
(Use delete_dir) 
(Use get_equa l_name_) 
(Establish on unit for cleanup 
condi t i on) 
wal k_subtree) 
hcs_$add_acl_entr i es, 
hcs_$add_di r_acl_entr i es, 
hcs_$del ete_ad_ent r i es, 
hcs_$del ete_d i r_acl_entr i es, 
hcs_$ 1 i st_acl , 
hcs_$ 1 i s t_d i r_ac 1 , 
hcs_$repl ace_acl , or 
hcs_$ replace_di r_acl ) 
hcs_$chname_f i 1 e or 
hcs_$ chname_seg ) 
hcs_$get_r i ng_brackets or 
hcs_$get_di r_ri ng^brackets, 
documented in the MPM Subsystem 
Writers' Guide) 
get_wdi r_) 
change__wdi r__) 



(Use 
(Use 



(Use 
(Use 



(Use cpu_t ime_and_pagi ng_) 

(Use get_process_i d_, get_group. 

get_pd \r__, or get_ring_) 
(Use t imer_manager_) 
(Use cpu_t ime_and_pag i ng_) 
(Use make_obj ect_map_) 
(Use move) 

(Use PL/1 array substitution) 
(Use cu ) 



id 
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pr i nt_obj ect_map 

pr i nthomedi r 
probe 

rever t_d eanup_proc_ 
sethomedi r 

set_search_di rector ies 
submi t_abs_request 
ti_ 

t io_ 



(Use pr i nt_1 i nk_J nfo with 

the -In control argument) 

(Use pr i nt_def aul t_wd I r ) 

(Use debug, dump_segment / 

1 i st__ref_nameS/ or trace__stack) 

(Revert on unit for cleanup conition) 

(Use change_defaul t_wdi r ) 

(Use set_search_di rs ) 

(Use enter_abs__request ) 

(Use tssi_, documented in the MPM 
Subsystem Writers' Guide) 

(Use ios ) 



Poi nters on Conver ti ne to New I nterf aces 



From time to time, as procedures become obsolete/ the 
following pages will be updated to supply information useful for 
converting old programs to work with new interfaces. 
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Name : decode__obj ect_ 



This subroutine was used to obtain pointers to the 
components of a segment in object format. The subroutine 
obj ect_i nf o__ now provides much more complete information about an 
object segment. Therefore, decode_obj ect_ i^ cons i dered obsolete 
and will eventually be removed from the system. 

Old Method 

declare decode_obj ect_ entry (ptr, fixed, fixed, ptr, fixed, 
f i xed) ; 

call decode_obj ect_ (segp, be, i, q, len, bits); 

1) segp is a pointer to the object segment. (Input) 

2) be is the bit count of the object segment pointed to by p. 

(Input) 

3) i indicates the desired component (standard assignments: 

1 ■ text, 2 = link, 3 = symbol). (Input) 

k) q is a pointer to the desired component, null if the 

component does not exist or the segment is not an 
object segment. (Output) 

5) len is the number of words occupied by the j_th component. 

(Output) 

6) lits is the bit count of the 1th component. (Output) 
Current Method 

declare obj ect_i nfo_$br i ef entry (ptr, fixed bin(24), ptr, 
fixed b!n<35)>; 

call obj ect_i nfo_$br i ef (segp, be, infop, code); 

1) segp is as above. 

2) be is as above. 

3) infop is a pointer to an info structure in which the object 

information is returned. (Input) 
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k) code is a standard Multics status code. (Output) 

Two other entries / $display and $long have identical calling 
sequences . 

The structure of the info segment is described in the MPM 
write-up of the obj ect_i nfo__ subroutine. 
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Name : move_ 

The function of this procedure (to rapidly copy a block of 
data from one place to another) is now implemented at least as 
efficiently by the PL/1 compiler. Therefore move_ is considered 
obsolete and will eventually be removed from the system. 
Procedures calling it should be modified to use in-line code as 
described below. 

Old Method 

declare move_ entry (ptr / ptr, fixed bin); 
call move_ (fromp, top, went); 

1) fromp is a pointer to the start of the data to be copied. 

(Input) 

2) top is a pointer to the start of the block where data is to 

be copied to. (Input) 

3) went is the number of words to be copied. (Input) 
Current Method 

declare block (went) fixed bin (35) based; 



top -> block ■ fromp -> block; 
where fromp, top, and went are as described above 
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Najafi: ti_ 

The ti_ subroutine provided an interface between translators 
and the storage system. The new subroutine, tssi_ (described in 
the MPM Subsystem Writers' Supplement)/ provides the same 
functions (setting up output segments, finishing them and 
cleaning up after an interrupt) for mul t i__segment files as well 
as for single segments. Note that only translator writers have 
need for this facility. 

Old Methods for Segments 

To set up an output segment: 

declare ti_$getseg entry (char(*) aligned, char(*) aligned, 
ptr, fixed bin(35), fixed bin); 

call ti_$getseg (dname, ename, segp, aclinfo, code); 

1) dname is the name of the directory in which the segment 

resides. (Input) 

2) ename is the name of the segment. (Input) 

3) segp is the pointer to the segment. (Output) 

h) aclinfo is coded information about where to find the 

segment's previous ACL saved. (Output) 

5) code is a standard Multics status code. (Output) 

To finish an output segment and give it "re" access: 

declare ti_$finobj entry (ptr, fixed bin(35), fixed bin(35), 
fixed bin); 

call ti_$finobj (segp, bitcnt, aclinfo, code); 

1) segp as above. (Input) 

2) bitcnt ?s the bit count of the output segment. (Input) 

3) aclinfo as above. (Input) 
k) code as above. (Output) 
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To finish an output segment and give it "rwa" access: 
declare ti__$findata entry (ptr, fixed bin(35), fixed bin(35), 



call ti__$findata (segp, bitcnt, aclinfo, code); 
Arguments are as for ti_$finobj. 

To clean up after an interrupt: 

declare ti_$clean_up entry (fixed bin(35)); 

call ti_$clean_up (aclinfo); 

The argument is as above. 

New Methods for Segments 

The entry tssi_$get_segment is equivalent to ti_$getseg, 
except that the fourth argument/ aclinfo, is a standard pointer 
datum rather than coded information. 

The entry tssi_$f i ni sh_segment performs the functions of 
both ti_$finobj and ti_$findata. It has an additional argument 
(in the third position) which specifes the access to be placed on 
the segment. Again, the aclinfo argument is a standard pointer 
datum. 

The entry tssi_$cl ean_up_segment is equivalent to 
t i_$cl ean_up, again with aclinfo a standard pointer datum. 

MuUi segment Fi les 

Entries for handling multisegment files do not exist in ti_. 
See the MPM Subsystem Writers 1 Supplement write-up of tssi_ for 
their usage. 



fixed bin); 
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STANDARD CHECKSUM 

This write-up describes a technique for computing a full 
word checksum on the Honeywel 1 6180 computer. This technique is 
the Multics standard technique, 

fllgor i thm 

Checksums are computed using the "awca" instruction followed 
by an "air 1" instruction. Upon completion of checksum 
computation / two "awca 0,dl" instructions are executed to include 
all carries in the checksum. 

A typical checksum computation scheme follows: 



ldi =o004000,d1 inhibit overflow fault 

sti indies save indicators 

Ida 0,d1 initialize "a" to zero 

eaxl 0 count locations in xl 

loop: ldi indies restore indicators 

awca word, 1 add with carry to checksum 

sti indies save indicators (they get 

clobbered by cmpxl) 

air 1 rotate "a" left 

eaxl 1,1 count 1 location and 

cmpxl size,du check for completion 

tnc loop loop 

Id? indies restore indicators 

awca 0 # dl add in carry, if any 

awca 0,dl in case carry generated by 

last instruction 

sta cksum save the checksum 
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HARDWARE FEATURE S JO AYGJLQ. 

This write-up documents a number of restrictions on usage of 
the 6180 that should be observed when writing programs to operate 
in the Multics environment. Some of these ^restrict ions are- 
enforced by the Multics supervisor; othersy~wh i 1 e not enforced/ 
should be followed to minimize the effect of potential supervisor 
or hardware changes. The Multics system uses these features, but 
does so in a controlled way. All instances of their use are 
localized in a very few procedure segments to minimize the 
effects of changes. 

Consult the 6180 processor manual for descriptions of the 
instructions and modifiers listed below. 

Hard-tO-tnterruPt Instructions and Modifiers 

The 6180 processor has in its repertoire a number of 
instructions and special modifiers with the property that an 
instruction, once begun: 

1) might not be able to complete execution because of a missing 
page or pending interrupt; 

2) cannot be scrapped and restarted from the beginning because a 
core location or register has already been modified. 

Such instructions must be interruptabl e in mid-execution in such 
a way that they can be continued at a later time; elaborate 
special -purpose hardware has been provided to snapshot the entire 
processor state including internal registers when an interrupt or 
fault occurs. 

The cost of providing this i nter ruptab i 1 i ty is quit high for 
two reasons. 

1) The speci al -purpose hardware is not needed for any other 
function. 

2) Every interrupt and fault (not just those occuring during 
execution of a hard-to- i nter rupt instruction) must be started 
and ended with a pair of relatively long instructions 
requiring 11 microseconds to save the snapshot in core, and 
restore it to the processor, repectively. In addition, 
following every fault or interrupt on which control was 
returned to the user, the store machine conditions must be 
checked for validity by a procedure that performs about a 
dozen tests. 
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Since it is unlikely that these continually paid costs are 
paid back by the time saved in occasional use of these 
instructions, a hardware change to force a compat i bl i i ty fault 
when they are used would allow removal of both of the above 
costs, and it would also permit addition of an interpreter 
procedure that simulates the effect desired but using more easily 
i nterrupt i bl e instructions. Thus it is unadvisable to utilize 
any of the instructions or modifiers in question, so as to make 
as simple as possible any future hardware change along this line. 

The following instructions and modifiers are included in the 
above discussion. 

1) instructions: 

XED Execute double 
RPT Repeat 
RPD Repeat double 
RPL Repeat link 

2) Modifiers that change the indirect word: 
CI 

Dl 

AD 

SD 

ID 

DIC 

IDC 

SC 

SCR 
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Extended Instruction Se. 



The 6180 has in its repertoire a set— orEZs i ngl e-word and 
multiple-word instructions for bit and character string 
manipulation and for decimal arithmetic. At present they do not 
work dependably and, thus, should be avoided. The following 
instructions make up the extended instruction set. 



MLR 

MRL 

MVE 

CMPC 

SCD 

SCDR 

TCT 

TCTR 

SCM 

SCMR 

MVN 

CMPN 

MVNE 

AD3D 

AD2D 

SB3D 

SB2D 

MP3D 

MP 2D 

DV3D 

DV2D 

CSL 

CSR 

SZTL 

SZTR 

CMPB 

DTB 

BTD 

LARn 

LAREG 

SARn 

SAREG 

AWD 

A9BD 

A6BD 

A^BD 

ABD 

SWD 

S9BD 



Move Alphanumeric Left to Right 
Move Alphanumeric Right to Left 
Move Alphanumeric Edited 
Compare Alphanumeric Character String 
Scan Character Double 

Double in Reverse 
and Translate 
and Translate in Reverse 



Scan 
Test 
Test 
Scan 
Scan 
Move 



in Reverse 



Character 
Character 
Character 
with Mask 
with Mask 
Numer i c 
Compare Numeric 
Move Numeric Edited 
Add Using 3 Decimal Operands 
Add Using 2 Decimal Operands 
Subtract Using 3 Decimal Operands 

2 Decimal Operands 

3 Decimal Operands 
2 Decimal Operands 
Decimal Operands 

2 Decimal Operands 
Strings Left 
Strings Right 
Truncation Indicators 
Truncation Indicators 
Str i ngs 



Subtract Using 
Multiply Using 
Multiply Using 
Di vi de Usi ng 3 
Divide Using 2 
Combined Bit 
Combined Bit 
Set Zero and 
Set Zero and 
Compare Bit 



wi th 
wi th 



Bit Strings Left 
Bit Strings Right 



Decimal to Binary Convert 

Binary to Decimal Convert 

Load Address Register n 

Load Address Registers 

Store Address Register n 

Store Address Registers 

Add Word Displacement to Specified AR 

Add 9-Bit Character Displacement to Specified AR 

Add 6-Bit Character Displacement to Specified AR 

Add U-Bit Character Displacement to Specified AR 

Add Bit Displacement to Specified AR 

Subtract Word Displacement from Specified AR 

Subtract 9-Bit Character Displacement from Specified AR 
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S6BD Subtract 6-Bit Character Displacement from Specified AR 

SkBD Subtract U-Bit Character Displacement from Specified AR 

SBD Subtract Bit Displacement from Specified AR 

AARn Alphanumeric Descriptor to ARn 

NARn Numeric Descriptor to ARn 

ARAn ARn to Alphanumeric Descriptor 

ARNn ARn to Numeric Descriptor 

LPL Load Pointers and Lengths 

SPL Store Pointers and Lengths 



(c) Copyright,- 1973- Massachusetts Institute of Technology 

and Honeywell Information Systems Inc. (END) 



MULTICS PROGRAMMERS 1 MANUAL 



9 



3/20/72 



COMMAN DS AMD. ACTIVE FUNCTIONS 

This section contains, in alphabetic order, descriptions of 
all standard Multics commands. The user of this section will 
also want to refer to the Reference Guide section on the Command 
Language Environment, which contains 

1. A guide to the commands, organized by function. 

2. An alphabetic list of command name abbreviations. 

3. A description of the Multics command language. 
k. An explanation of the role of active functions. 

The following conventions are used in command descriptions: 

1. In command usage, optional arguments are shown 
surrounded with hyphens. For example, 



locate namel -name2- 

would indicate that the locate command has a mandatory 
first argument and an optional second argument. 

2. In command usage, the ellipsis form 

aJL . . . an. 

is used to indicate a variable number of arguments all 
having the same form as al and an. 

Note that commands may be distinguished from subroutines by 
name; in general, subroutines have segment names which end with a 
trailing underscore. 

Commands not found in this section may possibly be listed in 
the Reference Guide sections on Obsolete Procedures or Internal 
I nter faces. 
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Name: abbrev, ab 

The abbrev command provides the user with a mechanism for 
abbreviating parts of (or complete) command lines in the normal 
command environment. 

When it is entered, the abbrev command sets up a special 
command processor that is invoked for each command line input to 
the system. The abbrev command processor checks each input line 
to see if is is an abbrev request line and, if so, acts on that 
request. (Requests are described below under Control Requests . ) 
If the input line is not an abbrev request line (recognized by a 
period (.) as the first nonblank character of the line) and 
abbreviations are included in the line, then the abbreviations 
are expanded once and the expanded string is passed on to the 
normal Multics command processor. The abbrev command processor 
is, therefore, spliced in between the listener and the normal 
command processor. 

Usag e 

abbrev 

Notes 

The abbrev command is driven by a user profile that contains 
information about a user's abbreviations as well as other 
information pertinent to abbrev's execution on behalf of that 
user. The profile is a segment which (by default only) resides 
in the home directory of the user. If the profile is not found, 
it is created and initialized. The name of the profile is 
personi d.prof i 1 e where personid is the login name of the user. 
For example, if the user Washington logged in under the project 
States, the default profile would be 

>user_di r_d i r>States>Wash i ngton>Wash i ng ton. prof i 1 e 

The profile being used by abbrev can be changed at any time 
with the .u control request (see below) to any profile in the 
storage system hierarchy to which the user has appropriate 
access. The entry name of a profile segment must have the suffix 
".profile". A new profile can be created by specifying a 
nonexisting segment to the .u control request. The segment is 
then created and initialized as a profile segment, assuming the 
user has the necessary access access permission. The user must 
be careful not to delete or terminate the segment that is 
currently being used as the profile. 
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The user can suppress expansion of a particular string in a 
command line by enclosing it within double quote characters ("). 
To supress expansion of an entire command line see the .<space> 
control request. 

A user might want to include the invocation of the abbrev 
command in a startup. ec segment so that he is automatically able 
to abbreviate whenever he is logged in. For an explanation of 
the startup. ec segment/ see the MPM Reference Guide section, 
Protocol for Logging In, under Start Up . 

control Requests 

Before abbrev expands a command line (to pass it on to the 
normal command processor), it first checks to see if the command 
line is an abbrev request line. An abbrev request line is 
recognized by its having a period (.) as the first nonblank 
character of the line. This means that an abbrev request is 
recognized only at the front of a command line. Any command line 
interpreted as an abbrev request line is treated specially and is 
neither checked for embedded abbreviations nor (even in part) 
passed on to the normal command processor. The one exception to 
this rule is a command line with a apsce character following the 
period; the rest of the line is passed to the normal command 
processor with no expansion being done. 

The character immediately after the period of an abbrev 
request line is the request name. The following requests are 
recogn i zed: 

.a <abbr> <rest of line> Add the abbreviation <abbr> to the 

current profile. It is an 
abbreviation for <rest of line>. 
Note that the <rest of line> string 
can contain any characters. If the 
abbreviation already exists, the 
user is asked if he wishes to 
redefine it. The user must respond 
with "yes" or "no". The 
abbreviation must be no longer than 
eight characters and must not 
contain break characters. The 
string it stands for must be no 
longer than 132 characters. 

,ab <abbr> <rest of line> Add an abbreviation which is 

expanded only if found at the 
beginning of a line or directly 
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.af <abbr> <rest of line> 



following a semicolon (;) in the 
expanded line. In other words, 
this is an abbreviation for a 

command name, 

Add an abbreviation to the profile 
and .force it to overwrite any 
previous abbreviation with the same 
name. The user is not asked if he 
wants the abbreviation redefined. 



.abf <abbr> <rest of line> 



Add an abbreviation which is 
expanded only at the keg inning of a 
line and force it to replace any 
previous abbreviation with the same 
name. The user is not asked if he 
wants the abbreviation redefined. 



.d <abbrl> ... <abbrn> 



.f 



Helete the specified abbreviations 
from the current profile. 



Enter a mode (the 
which forgets each 
after executing it. 
.s requests. 



default mode) 
command 1 ine 
See the . r and 



1 <abbrl> ... <abbra> 



.la <letterl> ... <lettera> 



J-ist the specified abbreviations 
with the strings they stand for. 
If no abbreviations are specified, 
all abbreviations in the current 
profile are listed. If no letters 
are specified, all abbreviations in 
the current profile are listed. 

List all abbreviations starting 
with the specified letters. 
<letterX> is expected to be a 
single character. If no letters 
are specified, all abbreviations in 
the current profile are listed. 

&uit. This request resets the 
command processor to the one in use 
before invoking abbrev and, hence, 
prevents any subsequent action on 
the part of abbrev until it is 
explictly invoked again. 
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. r Enter a mode which remembers the 

last line expanded by abbrev. See 
the .f and the .s requests. 

.s <rest of line> S.how the user how <rest of line> 

would be expanded but do not 
execute it. The .s request with no 
arguments shows the user the last 
line expanded by abbrev, and is 
valid only if abbrev is remembering 
lines. See the .f and ,r requests. 

.u <profile> Specify to abbrev the profile that 

the user wants to use. <profile> 
is the pathname of the profile to 
be used and can contain 
abbreviations already defined. 

.p This request p.rints the name of the 

profile being used. 

,<space> <rest of line> If the request character is a 

space, the entire command line is 
passed on to the normal command 
processor (after removing the 
period) with no expansion being 
performed. The user can thus issue 
a command line that contains 
abbreviations that are not to be 
expanded. 

Preak characters 

When abbrev expands a command line, it treats certain 
characters as special or break characters. Any character string 
which is less than or equal to eight characters long and is 
bounded by break characters is a candidate for expansion. The 
string is looked up in the current profile and, if it is found, 
the expanded form is placed in (a copy of) the command line to be 
passed on to the normal command processor. 

The characters which abbrev treats as break characters are: 
tab 

new line 
space 

double quote " 
dollar sign $ 
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apost raphe 
period 
semi col on 
vertical bar 
parentheses 
less than 
greater than 
brackets 
braces 



( ) 

< 
> 



C ] 

{ } 



Example 



Suppose that a user notices that he is typing the segment 
name suffixes "fortran" and "incl . fortran" a lot as he edits his 
FORTRAN source segments. He might wish to abbreviate them to 
"ft" and "ift" respectively. He then types the lines specified 
to accomplish the following objectives: 

1) Invoke the abbrev command 



2) Define the two abbreviations 

.a ft fortran 

.a ift incl .fortran 

3) Now that "ft" and "ift" are defined, invoke the text editor, 
edm, to create or edit his source segments 

edm sample. ft 
edm insert. ift 

h) Print the include file 



Note that if the user chooses to write out one of the 
segments from edm by a different name, he must type the expanded 
name since the edm command (and not the abbrev commmand 
processor) is intercepting all terminal input. For example, 
after editing sampl e. fort ran he might wish to write out the 
changed version as example. fortran . He would type to edm 

w example. fortran 

However, if he typed 

w example. ft 

he would create a segment by exactly that name (example. ft ) . 



abbrev 



print insert. ift 
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Name ; addname/ an 

The addname command adds an alternate name to the existing 
name(s) of the segment/ directory/ or link specified. See also 
deletename and rename in the MPM. 

Usage 

addname path entryl ... entryjn 

1) path is the path name of the segment/ directory/ or link 

to which an additional name is to be added. 

2) entryl is the additional name(s) to be added to the 

segment/ directory/ or link. 

Notes 

The user must have v/rite access on the directory 
containing the segment/ directory/ or link to be modified. 

The equals and star conventions may be used. 

The entryl argument must be unique in the directory. If 
there is a duplication/ the initial instance of entryl will be 
removed and the user will be informed of this action/ unless 
removing the initial instance would leave the segment/ directory/ 
or link without a name. In the latter case, the user will be 
interrogated as to whether he wishes the segment, directory/ or 
link deleted; if he does not, entryl will not be added to the 
segment, directory/ or link specified. 

Example 

addname >sys_l ib>Smi th .Mul t ics .pi 1 Jones. « 

would add the name Jones .Mul t i cs .pi 1 to the segment 
Smith.Multics.pl! in the directory sys_lib. 
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Name : adjust_bi t_count, abc 



The adjust_bi t_count command may be used to set the bit 
count of segments which for some reason do not have the bit count 
set properly (e.g., the program which was creating the segment 
got a fault, or the process terminated without the bit count 
be i ng set, etc. ). 

Usage 

adjust_b i t_count pathl. ... pathn -option- 
1) pathl are the pathnames of the segments to be adjusted. 



2) option may be -character (-ch). If the option occurs 
anywhere on the command line, it applies to all 
pathname arguments such that resetting of the bit 
count is done to the last nonzero character in the 
segment. The default is to reset the bit count to 
correspond to the last nonzero 36 bit word in the 
segment . 

If the bit count could be computed but could not be 
reset (e.g., improper access to the segment), the 
computed value will be printed such that the user 
may then use the set_bi t_count command (see the MPM) 
after resetting access or other necessary corrective 
measures . 
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Name : aim 

ALM is the standard Multics assembly language. It is 
commonly used for privileged supervisor code, compiler support 
operators and utility packages, and data bases. It is 
occasionally used for efficiency or to use hardware features not 
accessible in compiler languages; however, its routine use is 
d i scouraged . 

The ALM language is described briefly in this section as 
there is no language reference manual available to users. The 
6180 Processor Reference Manual has not yet been published, but 
the 6U5 Processor Reference Manual (amended for 6180 processor) 
can be used to understand the instruction set. 



The aim command 
containing the 



invokes the ALM assembler to translate a 
segment containing the text of an assembly language program into 
a Multics standard object segment. A listing segment can also be 
produced. These segments are placed in the user's current 
working directory. 



Usage 

aim segment_name 

1) segment_name 

2) control__arguments 

-list, -Is 
-no_symbol s 



-quiet, -qe 



-cont rol__arguments- 

specifies the path name of the source 
program to be assembled. The suffix 
".aim" is added automatically by the aim 
command unless it is already present. 

control optional functions of the 
assembler. They can only appear after 
the segment_name argument, and none are 
required. Legal control arguments are: 

An assembly listing segment is produced 
if and only if this control argument is 
speci f ied. 

By default the listing segment produced 
by the -list control argument contains a 
cross-reference table. This control 
argument suppresses the table. 

This control argument prevents errors 
from being typed out on the terminal. 
Errors are flagged in the listing (if 
any) in any case. 
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Notes 

The entry name of an ALM source segment consists of the name 
of the object segment concatenated with the string ".aim". 
Similarly the name of the listing segment produced by the 
assembly has a name consisting of the name of the object segment 
concatenated with the string ".list". The pathname argument to 
the aim command identifies the source segment; if the ".aim" 
suffix is omitted/ the command appends it. This does not affect 
the names of the object and listing segments. 

The assembly listing is made into a multisegment file if 
necessa ry . 

The assembler is serially reusable and sharable, but not 
reentrant. That is, it cannot be interrupted during execution, 
invoked again, then restarted in its previous invocation. 

Error Cond i t ions 

Errors arising in the command interface, such as inability 
to locate the source segment, are reported in the normal Multics 
manner. Some conditions can arise within the assembler that are 
considered to be malfunctions in the assembler; these are 
reported by a line typed out and also in the listing. Either of 
the above cases is immediately fatal to the translation. 

Errors detected in the source program, such as undefined 
symbols, are reported by placing one-letter error flags at the 
left margin of the offending line in the listing file. Any line 
so flagged is also printed on the user's terminal, unless the 
-quiet control argument is in effect. Flag letters and their 
meanings are given below. 

B mnemonic used belongs to obsolete (61*5) processor 
instruction set. 

C obsolete (645 compatibility check). 

E malformed expression in arithmetic field. 

F error in formation of pseudo-operation operand field. 

M reference to a multiply-defined symbol. 

N un impl emented or obsolete pseudo-operation. 

0 unrecognized opcode. 
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P phase error. Location counter at this statement has 
changed between passes, possibly due to misuse of org 
pseudo-operat ion . 

R expression has invalid relocatabi 1 i ty . 

S error in the definition of a symbol. 

T undefined modifier (tag field). 

U reference to an undefined symbol. 

X segdef pseudo-operation used in mastermode or 
executeonly procedure. 

7 digit 8 or 9 appears in an octal field. 

The errors B, E, M, 0, P, and U are considered fatal. If 
any of them occurs, the standard Multics "Translation failed" 
error message is reported after completion of the translation. 

AIM language 

An ALM source program is a sequence of statements separated 
by new line characters or semicolons. The last statement must be 
the end pseudo-operation. 

Fields must be separated by white space, which is defined to 
include space, tab, new page, and percent characters. 

A name is a sequence of upper and lower case letters, 

digits, underscores, and periods. It must begin with a letter or 
underscore, and cannot be longer than 31 characters. 

labels 

Each statement can begin with any number of names, each 
followed immediately by a colon. Any such names are defined as 
labels, with the current value of the location counter. Note 
that a label on a pseudo-operation that changes location counters 
or forces even alignment (such as org or i ts ) might not refer to 
the expected location. White space can appear before, after, or 
between labels, but not before the colon, and no white space is 
requ i red . 
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Opcode 

The first field after any labels is the opcode. It can be 
any instruction mnemonic described in the appropriate processor 
reference manual, or any one of the pseudo-operations listed 
below. ft can be omitted, and any labels are still defined. 
White space can appear before the opcode, but is not required. 



Operand 

Following the opcode, and separated from it by mandatory 
white space, is the operand field. For instructions, the operand 
defines the address, base, and tag (modifier) of the instruction. 
For each pseudo-operation, the operand field is described below 
in the list of pseudo-operations. The operand field can be 
omitted in an instruction. Those pseudo-operations that use 
their operands generally do not permit the operand field to be 
omi tted . 



Comments 



Since the assembler ignores any text following the end of 
the operand field, this space is commonly used for comments. In 
those pseudo-operations that do not use the operand field, all 
text following the opcode is ignored and can be used for 
comments. Also, a quote character (") in any field introduces a 
comment that extends to the end of the statement. (The only 
exceptions are the acc and ac i pseudo-operations, for which the 
quote character can be used to delimit literal character 
strings.) Note that semicolon ends a statement and therefore ends 
a comment as wel 1 . 



Instruction Operands 

The operand field of an instruction can be of several 
distinct formats. Most common is the direct specification of 
base, address, and modifier. This consists of three subfields, 
any of which can be omitted. The first subfield specifies a base 
register by number, user-defined name, or predefined name (ap, 
ab, bp, bb, Ip, lb, sp, sb). The subfield ends with a vertical 
bar. If the base register and bar are omitted, no base register 
is used in the instruction. 



The second subfield is any arithmetic expression, 
relocatable or absolute. This is the address part of the 
instruction, and defaults to zero. Arithmetic expressions are 
defined below. 
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The last subfield is the modifier or tag. It is separated 
from the preceding subfields by a comma. If the tag subfield and 
comma are omitted / no instruction modification is used. (This is 
an all zero modifier.) Legal modifiers are defined below. 



Other formats of instruction 
registers. These cannot have 
specified explicitly. 



operands are used to 
the base register 



imply base 
subf i el d 



If a symbolic name defined by temp , tempd , or temp8 is used 
in the address subfield (it can be used in an arithmetic 
expression) then the base register sp is implied. This form can 
have a tag subfield. 

Similarly, if an external expression is used in the address 
subfield then the base register lp is implied; this causes a 
reference through a link. If a modifier subfield is specified, 
it is taken as part of the external expression; the instruction 
has an implicit jh modifier to go through the link pair. 
External expressions are defined below. 

A literal operand begins with an equals sign followed by a 
literal expression. The literal expression can be enclosed in 
parentheses. It has no base register but can have a tag 
subfield. A literal reference normally causes the instruction to 
refer to a word in a literal pool that contains the value of the 
literal expression. However, if the modifier du. or dj_ is used, 
the value of the literal is placed directly in the instruction 
address field. Literal expressions are defined below. 

Examples of Instruction Statements 
xlab: 



Ida 


ap|2,* 


it 


Exampl e 


1. 


eax7 


xlab-1 








reel 


<sys__info>| clock_ ,* 


it 


Exampl e 


2. 


segref 


sys_info, t ime_del ta 


ii 


Exampl e 


3. 


adl 


t ime_del ta+1 








temp 


next i 


ii 


Exampl e 


k . 


1x10 


next i , * 








1 ink 


goto, <unwi nder_> | unwinder__ 


it 


Exampl e 


5. 


tra 


lplgoto,* 








ana 


=o777777,du 


n 


Exampl e 


6. 


ada 


=v36/l ist_end-l 
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Example 1 shows direct specification of address, base, and 
tag fields. In the second instruction, no base is specified, and 
the symbol xlab is not external, so no base is used. 

Example 2 shows an explicit link reference. Indirection is 
specified for the link as the item at clock_ (in sys_info) is 
merely a pointer to the final operand. 

Example 3 uses an external expression as the operand of the 
adl instruction. In this particular case, the operand itself is 
in sys_info. 

Example h uses a stack temporary. Since the word is 
directly addressable using sp, the modifier specified is used in 
the instruction. 

Example 5 shows a directly specified operand that refers to 
an external entity. It is necessary in this case to specify the 
base and modifier fields, unlike segref . 

Example 6 uses two literal operands. Only the second 
instruction causes the literal value to be stored in the literal 
pool . 

Ari thmet ic Expression 

An arithmetic expression consists of names (other than 
external names) and decimal numbers joined by the ordinary 
operators + - * /. Parentheses can be used with the normal 
mean ing. 

An asterisk in an expression, when not used as an operator, 
has the value of the current location counter. 

All intermediate and final results of the expression must be 
absolute or relocatable with respect to a single location 
counter. A relocatable expression cannot be multiplied or 
divided. 

Log i cal Express ion 

A logical expression is composed of octal constants and 
absolute symbols combined with the Boolean operators + (OR), - 
(XOR), * (AND), and ~* (NOT). Parentheses can be used with the 
normal meaning. 
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External Express ion 

An external expression refers symbolically to some other 
segment. It consists of an external name or explicit link 
reference, an optional arithmetic expression added or subtracted, 
and an optional modifier subfield. An external name is one 
defined by the segref pseudo-operation. An explicit link 
reference must begin with a segment name enclosed in angle 
brackets and followed by a vertical bar. This can optionally be 
followed by an entry name in square brackets. For example: 

<segname>| entryname 
<segname> | 0, 5* 

A segment name of *text or *link indicates a reference to 
this procedure's text or linkage sections. 

A link pair is constructed for each combination of segment 
name, entry name, arithmetic expression, and tag that is 
referenced . 

Literal Expression 

A literal reference causes the instruction to refer to a 
word in a literal pool that contains the value specified. An 
exception occurs, in that the modifiers du. and dj_ cause the value 
to be stored directly in the address field of the instruction; 
the effect is the same when executed. The various formats of 
literals are described as follows. 

A decimal literal can be signed. If it contains a decimal 

point or exponent, it is floating point. If the exponent begins 
with "d" instead of "e, it is double precision. A binary scale * 
factor beginning with "b 11 indicates fixed point, and forces 
conversion from floating point. 

An octal literal begins with an "o" followed by up to twelve 
octal digits. 

ASCII literals can occur in two forms: one begins with a 
decimal number between 1 and 32 followed by "a" followed by that 
many data characters, which can cross statement delimiters. The 
other form begins with "a" followed by up to four data 
characters, which can be delimited by the new line character. 

A GBCD literal begins with "h" followed by up to six data 
characters, which can be delimited by the new line character. 
Translation is performed to the 6-bit character code. 
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An ITS ( ITP. ITB) literal begins with "its" ("itp M , "itb") 
followed by a parenthesized list containing the same operands 
accepted by the i ts ( i to , i tb ) pseudo-operation. The value is 
the same as that created by the pseudo-operation. 

A variable-field literal begins with "v" followed by any 
number of decimal, octal/ and ASCII subfields as in the vf d 
pseudo-operation. It must be enclosed in parentheses if a 
modifier subfield is to be used. 

Modi f iers 

These specify indirection/ index register address 
modification/ immediate operands, and miscellaneous tally word 
operations. They can be specified as 2-digit octal numbers 
(particularly useful for instructions like stba ) . or symbolically 
using the mnemonics described here. 

Simple register modification is specified by using any of 
the register designators listed in the table. It causes the 
contents of the selected register to be added to the final 
effective address. 

Register-then-indirect modification is specified by using 
any of the register designators followed by art asterisk. If the 
asterisk is used alone it is equivalent to the jq*. modifier. The 
register is added into the effective address, then the address 
and modifier fields of the word addressed are used in determining 
the final effective address. Indirection cycles continue as long 
as the indirect words contain an indirection modifier. 



Indirect-then-register modification is specified by placing 
an asterisk before any one of the register designators listed 
below. See the processor manual . 

Direct modifiers are du and dj_. They cause an immediate 
operand word to be fabricated from the address field of the 
instruction. For dJL, the 18 address bits are right-justified in 
the effective operand word; for du. they are 1 ef t- j us t i f i ed. In 
either case, the remaining 18 bits of the effective operand are 
f i 1 1 ed wi th zeros . 



Segment addressing modifiers i ts , i tb , and i tp can only 
occur in an indirect word pair on a double-word boundary. i ts 
causes the address field of the even word to replace the segment 
number of the effective address, then continues the indirect 
cycle with the odd word of the pair. Nearly all indirection in 
Muitics uses ITS pairs. For i tb and i tp , see the processor 
manua 1 . 
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Tally modifiers 1/ c i , sc , scr , ad., s_d, j_ci, djL idc , and die 
control incrementing and decrementing of the address and tally 
fields in the indirect word. They are difficult to use in 
Multics because the indirect word and the data must be in the 
same segment. See the processor manual. 



Fault tag modifiers £1, f2., and £3. cause distinct hardware 
faults whenever they are encountered. £2. is reserved for use in 
the Multics dynamic linking mechanism; the others result in the 
signalling of the conditions "f au 1 t_tag_l" and "f au 1 t_tag_3 , \ 

designators register 

xO 0 index register 0 

xl 1 index register 1 

x2 2 index register 2 

x3 3 index register 3 

xk k index register k 

x5 5 index register 5 

x6 6 index register 6 

x7 7 index register 7 

n none (no modification) 

au A bits 0-17 

al A bits 18-35 or 0-35 

qu Q bits 0-17 

ql Q bits 18-35 or 0-35 

ic instruction counter 

EIS modifiers 

An EIS modifier appears in the first word of an EIS 
multi-word instruction. It affects the interpretation of operand 
descriptors in subsequent words of the instruction. No check is 
made by ALM that the modifier specified is consistent with the 
operand descriptor specified elsewhere. 

An EIS modifier consists of one or more subfields separated 
by commas. Each subfield contains either a keyword as listed 
below, or a register designator, or a logical expression. The 
values of the subfields are 0R f ed together to produce the result. 

keyworq* meaning 

pr Descriptor contains a base register reference, 
id Descriptor is an indirect word pointing to the true 
descr i ptor . 

rl Descriptor length field names a register containing 
data length. 
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Pseudo-operat ions 



end 

terminates the source file. 



i ncl ude segmentname 
inserts the text of the segment segmentname . incl .aim immediately 
after this statement. A standard include library search is done 
to find the include file. See the MPM Reference Guide section/ 
The System Libraries and Search Rules. 



name objectname 
respecifies the object segment name as it appears in the object 
segment. By default the storage system name is used. 



use name 

assembles subsequent code into the location counter name . 
Default location counter is ".text.". 



join / tex t/ name 1 , name2 . . . . / 1 ink/ name3 , name** . . . . 

appends the location counters namel , name2 , etc. to the text 
section, and appends the location counters name3 , name** , etc. to 
the linkage section. The text and link parts can be used alone 
or together; any number of names can appear. Each name must have 
been previously referred to in a use statement. Any location 
counters not io i n ed are appended to the text section. 



org expression 
sets the location counter to the value of the absolute arithmetic 
expression express ion . The expression must not use symbols not 
previously defined. 



even 

odd 

eight 

sixtYfoiir 

inserts padding (nop) to a specified word boundary, 

mod expression 
inserts padding (nop) to an ( express ion ) word boundary. 

mastermode 
executeonl v 

requests special entry-checking code. Obsolete. 

inhibit oji 
inhibit off 

sets a mode affecting interrupt inhibit bit that is assembled 
into subsequent instructions. For system use. 
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nul 1 

rem 

is ignored. Used for comments. 



bool name, express i on 

defines the symbol name wi th the logical value express ion . See 
the definition of logical expressions above. 

eau name, express ion 

defines the symbol name with the arithmetic value express ion . 

set name, express ion 

assigns the arithmetic value express ion to the symbol name . Its 
value can be reset in other set statements . 



link name, extexpress i on 

defines the symbol name with the value equal to the offset from 
lp to the link pair generated for the external expression 
extexoression . Note that an external expression can include a 
tag subfield. Note also that name is not an external symbol, so 
an instruction should refer to this link by: 

lolname,* 

segref segname,namel,name2, . . . 
defines the symbols namel, name2, etc. as external symbols 
referencing the entry points namel , name2 , etc. in segment 
segname . This defines a symbol with an implicit base register 
reference. 

temp namel (nl), name2 (n2 ) , . . . 

defines the symbols namel , name2 . etc. to reference unique stack 

temporaries of ni, nl, etc. words each. nl. nl/ etc. are 
absolute arithmetic expressions, and can be omitted (the 
parentheses should also be omitted). The default is one word per 
name. 

temod namel(nl),name2(n2), . . . 
is similar to temp , except that n_l (nl, etc.) double words are 
allocated, each on a double word boundary. 

temo8 namel(nl),name2(n2), . . . 

is similar to temp , except that 8-word units are allocated, each 
on an 8-word boundary. 
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acc /string/ 
assembles the ASCII string str i ng into as many contiguous words 
as are required (up to forty-two). The delimiting character / 
can be any non-white-space character. The quoted string can 
contain new line and semicolon characters. The length of the 
string is placed in the first character position in acc format. 

acl /string/ 
is similar to acc , but no length is stored. The first character 
position contains the first character in ac i format. 

bci /string/ 
is similar to ac i , but uses GBCD six-bit character codes. 

dec numberl, number2 / . . . 

assembles the decimal integers numberl , number2 , etc. into 
consecutive words. 

oct numberl, number2, . . . 

is like dec , with octal integer constants. 

zero express i onl, express i on2 

assembles express i onl into the left 18 bits of a word and 
express ion2 into the right 18 bits. Both subfields default to 
zero. 

are operand 
is assembled exactly like an instruction with a zero opcode. Any 
form of instruction operand may be used. 

vf d TILl/express ionl,T2L2/express ion2, . . . 

is variable format data, express ioni is of type XI and is stored 
in the next U_ bits of storage. As many words are used as 
required. Individual items can cross word boundaries and exceed 
36 bits in length. Type is indicated by the letters "a" (ASCII 
constant) or "o" (logical expression) or none (arithmetic 
expression). Regardless of type, the low order Lj. bits of data 
are used, padded if needed on the left. Tj. can appear either 
before or after L i . 

Restrictions: The total length cannot exceed ten words. A 
relocatable expression cannot be stored in a field less than 18 
bits long, and it must end on either bit 17 or bit 35 of a word. 

bss name, express ion 

defines the symbol name as the address of a block of express i on 
words at the current location, name can be omitted, in which 
case the storage is still reserved. 
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bf s name, express ion 

is like bss , but name is defined as the address of the first word 
after the block reserved. 

i ts segno, of f set, tag 

generates an ITS pointer to the segment segno , word offset 
offset , with optional modifier tag . If the current location is 
not even, a word of padding (nop) is inserted. Note that such 
padding causes any labels on the statement to be incorrectly 
def i ned. 

i to baseno,of f set, tag 

i tb baseno,of f set, tag 

generates an ITB (ITP) pointer referencing the base register 
baseno . Not commonly used in Multics. 

f i rstref extexpress ionKextexpress ion2 ) 
the procedure extexpress ionl is to be called with the argument 
pointer extexpress ion2 the fiTst time (in a process) that this 
object segment is linked to by an external symbol. If 
extexpress ion2 and the parentheses are omitted, an empty argument 
list is supplied. The expressions are any external expressions, 
including tags. 

segdef namel, name2, . . . 
makes the labels namel. name2 , etc. available to the linker for 
referencing from outside programs, using the symbolic names 
namel , name 2 , etc. Such incoming references go directly to the 
labels namel , name2 , etc., so the segdef pseudo-operation is 
usually used for defining external static data. For program 
entry points the entry pseudo-operation is usually used. 

entry namel, name2, . . . 

generates entry sequences for labels namel , name2 , etc. and makes 
the externally-defined symbols namel , name2 , etc. refer to the 
entry sequence code rather than directly to the labels. The 
entry sequence performs such functions as initializing base 
register lp to point to the linkage section, which is necessary 
to make external symbolic references ( 1 ink , segref , explicit 
links). The entry sequence can use (alter) base register bp, 
index registers 0 and 7, and the A and Q. It requires sp and sb 
to be properly set (as they normally are). 

sets the base register lp to point to the linkage section. This 
can be used with segdef to simulate the effect of entry . This 
operator can use base register bp, index registers 0 and 7, and 
the A and Q, and requires sp and sb to be set properly. 
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save expression 

push expression 
creates a new stack frame for this procedure/ containing 
expression words. If express i on is omitted (the usual case), the 
frame is just large enough to contain all cells reserved by temp , 
temod , and temp8 . This operator can use base registers bp and 
sp, index registers 0 and 7, and the A and Q/ and requires sp and 
sb to be set properly. 

short return 

is used to return from a procedure which has not performed a 
save . This operator requires sp and sb to be set properly. 

return 

is used to return from a procedure which has performed a save . 
This operator requires sp and sb to be set properly. 

cal 1 rout i ne(argl i st ) 

calls out to the procedure rout i ne using the argument list at 
arel i st . Both rout i ne and are! i st can be any legal instruction 
operand/ including tags. If arel i st and the parentheses are 
omitted, an empty argument list is created. All registers are 
saved and restored by cal 1 . This operator requires that sp and 
sb be set properly. 

short cal 1 routine 
calls out to rout i ne using the argument list pointed to by ap. 
Only lp/ sp/ and sb are preserved by short cal 1 , and sp and sb 
must be properly set. 

rpt tal 1 y/del ta, terml/ term2/ . . . 

generates the machine rpt instruction as described in the 
processor manual. tal 1 v and del ta are absolute arithmetic 
expressions. The termi specify the termination conditions as the 
names of corresponding conditional transfer instructions. This 
same format can be used with the rpt , rpd , rpda , and rpdb 
pseudo-ope rat ions * 

rotx /delta 

generates the machine rpt instruction with a bit set to indicate 
that the tally and termination conditions are to be taken from 
index register 0. This format can be used with rol x and rodx . 

eax i ndex/ operand 

assembles into an eaxn instruction, where n is the value of the 
absolute arithmetic expression i ndex . This format can be used 
for all index register instructions. 
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tsp base, operand 

assembles into a tspn instruction/ where jn is found as follows: 
If base is a built-in base name (ap, ab, etc.) that register is 
selected. Otherwise/ base must be an absolute arithmetic 
expression whose value is &. This format can be used for all 
base register instructions except spr i . 

awd operand 

awdx operand 
generates the 6180 EIS instruction awd as described in the 
processor manual, operand must specify a base register, as this 
instruction selects its output register that way. The awdx 
pseudo-operation causes the offset to be cleared before the 
addition, thus effecting a load. This format can be used with 
abd , afrbd , sbd , sbdx , etc. 

ml r (MFD . (MF2K f i 1 1 (octexoress i on) , enabl ef aul t 

generates the first word of an EIS multiword instruction. MF1 
and MF2 are EIS modifier fields as described above. Certain 
keywords ( fill , boo! , and mask ) require logical expression 
operands that specify the bits to be placed in the appropriate 
parts of the instruction. Other keywords ( round , enabl ef aul t , 
asc i i ) cause single option bits in the instruction to be set. 
Keywords can occur in any order, before or after any MF fields. 
This format can be used for all 6180 EIS mul t i word instructions. 



descUa address (of f set ), 1 ength 
desc6a address (of f set )/ 1 ength 
desc9a address (of f set ), 1 ength 

generates the operand descriptor that usually follows the first 
word of an EIS multiword instruction, address is any arithmetic 
expression/ possibly preceded by a base register subfield as in 
an instruction operand. offset is an absolute arithmetic 
expression giving the offset (in characters) to the first bit of 
data. It can be omitted if the parentheses are also omitted. 
1 ength is either a built-in index register name (al/ au, ic, xO, 
etc.) or an absolute arithmetic expression for the data length 
field of the descriptor. The character size (in bits) is 
specified as part of the pseudo-operation name. 



descb address (of f set )/ 1 ength 



generates an operand descriptor for a bit string. offset and 
1 ength are in bits. 
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desgfrns 



address(offset), length, scale 
address (off set ), length, scale 
address (of f set ), 1 ength, seal e 
address (offset ) , 1 ength, seal e 



generates an operand descriptor for a decimal string. scale is 
an absolute arithmetic expression for a decimal scaling factor to 
be applied to the operand. It can be omitted, and is ignored in 
a floating-point operand. Data format is specified in the 
pseudo-operation name: descUf 1 indicates floating point, descUl s 
indicates leading sign fixed point, descfrns indicates unsigned 
fixed point, and deserts indicates trailing sign fixed point. 
Nine-bit digits can be specified by using desc9f 1 . desc9 1 s . 





desc9ns, and desc9ts. 
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Name ; alm_abs, aa 



This command submits an absentee request to perform ALM 
assemblies. The absentee process for which alm_abs submits a 
request assembles the segments named, appends the output of 
pr i nt_J i nk_i nf o for each segment to the segment segnamel. 1 i st if 
it exists, and dprints and deletes segnamel. 1 i st . If the 
-output_file control argument is not specified, an output 
segment, segname . absout, is created in the user's working 
directory (if more than one segname is specified, the first is 
used). If the segment to be assembled cannot be found, no 
absentee request is submitted. 



Usage 



alm_abs segnamel ... segnamen -alm_cont ro1__args- 
-alm_ abs_control_args- 



1) segname J. 

2) alm_cont rol_args 

3) alm_abs_control__ args 
-queue q., ~q a 



-copy a/ -cp a 



-hold 



is the path name of 
assembl ed. 



segment to be 



can be one or more nonobsolete control 
arguments accepted by the ALM assembler 
and described in aim. (See the write-up 
in the MPM.) 



can be one or more 
control arguments: 



of the 



fol lowi ng 



specifies in which priority queue the 
request is to be placed (a <= 3). The 
default queue is 3. segnamei. 1 i st is 
also dprinted in queue a* 

specifies the number of copies (a <■ *0 
of segnamel. 1 i st to be dprinted. The 
default is 1. 

specifies that alm_abs should not dprint 
or delete segnamel. 1 i st . 



-output_ file £, -of £ specifies that absentee output is to go 

to segment f. where £ i s a path name. 
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NoJias 

Control arguments and segment names can be mixed freely and 
can appear anywhere on the command line after the command. All 
control arguments apply to all segment names. An unrecognizable 
control argument causes the absentee request not to be submitted. 

Expanded segments containing include files are not deleted. 

Unpredictable results can occur if two absentee requests are 
submitted which could simultaneously attempt to assemble the same 
segment or write into the same .absout segment. 

When doing several assemblies, it is more efficient to give 
several segment names in one command rather than several 
commands. With one command, only one process is set up. Thus 
the links that need to be snapped when setting up a process and 
when invoking the assembler need be snapped only once. 
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Name : answer 

This command provides a preset answer to any questions asked 
by some other command. It does this by establishing a handler 
for the condition command_ques t i on, and then executing the 
subject command. If the subject command calls comma nd_query_ to ^ 
ask a question, the handler will be invoked to supply the answer. 
The handler is reverted when "answer" exits. 

Usage 

answer ans -cont rol__args- commandline 

1) ans is the desired answer to any question. 

2) cont rol__args may be chosen from the following list of 

control arguments: 

-brief, -bf suppresses printing of both the question and 

the answer. 

-times n gives the prespecified answer n times only 

(where n is an integer); then it acts as if 
"answer" had not been called. 

3) commandline is any Multics command line. 
Notes 

If a question is asked which requires a yes or no answer, 
and the preset answer is neither yes nor no, the handler will not 
be invoked. 

Examol es 

To delete a directory without being asked if you want to 
delete it: 

answer yes -bf dd test_dir 

To see the first three blocks of an info segment named 
f red. info, and then be interrogated: 

answer yes -times 2 help fred 

To see only the first three blocks: 
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answer no answer yes -times 2 help fred 

In the above example, "answer" is invoked twice. The first 
invocation is to answer no and is given the command line 

answer yes -times 2 help fred 

The second invocation is to answer yes twice, and is given the 
command 1 i ne 

help fred 

The help command prints the first block of fred. info, and gets 
the answer yes from the second invocation of "answer". It 
repeats this process, and again obtains a yes answer. After help 
prints the third block of fred. info, however, the second 
invocation of "answer" has had its count run out, and behaves as 
if it had not been called. Hence, the first invocation of 
"answer" supplies the answer no and execution ends. 
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Name : apl 

The apl command invokes the Multics APL interpreter, which 
is completely described in the APL User's Guide. The Multics APL 
language is nearly identical to the language APL/360, which has 
earned wide acceptance. 

APL can be characterized as a 1 i ne-a t-a-t ime desk calculator 
with many sophisticated operators and a limited stored-program 
capability. One needs little or no prior acquaintance with 
digital computers to make use of it. After invoking APL, one 
types an expression to be evaluated. The APL interpreter 
performs the calculations/ prints the result, and awaits a new 
input line. The result of an expression evaluation can also be 
assigned to a variable and remembered from line to line. In 
addition, there is a capability for storing up input lines and 
giving them a name, so that a later mention of the name causes 
the 1 ines to be brought forth and interpreted as if they had been 
entered from the console at the time. Finally, there is also the 
ability to save the entire state of an APL session, complete with 
all variable values and stored programs, so that it can be taken 
up again on another day. 

Usage 

apl 

Notes 

There are no arguments. The interpreter responds by typing 
six spaces and awaiting input. For further information, consult 
the APL User's Guide. 
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Name : archive/ ac 

An archive segment is a single segment which is formed by 
combining together an arbitrary number of separate segments; 
these constituent parts of an archive segment are called 
components . The archive segment is particularly useful as a 
means of conserving storage space by eliminating the breakage 
which occurs when the contents of segments do not fill complete 
pages of storage. It is convenient as a means for packaging 
segments; it is used in that manner when interfacing with the 
Multics binder. 

The archive command is furnished to maintain archive 
segments for the user. There are four general classes of 
operations performed by the archive command. These are: 

1) printing a table of contents; 

2) extracting components; 

3) deleting components; 

k) replacing/ updating/ or appending components. 

The first two classes of operations use the contents of archive 
segments; the last two classes of operations change the contents 
of archive segments. Various features are combined with these 
operations to ease the use of archive segments. 

The copy feature may be combined with the replacement and 

deletion operations. It causes the updated archive to be placed 

in the working directory when the original archive segment is 

found elsewhere in the storage system. The copy feature behaves 

as if the archive, segment were first copied into the user's 
working directory and then updated as requested. 

Deletion can be combined with the replacement operations to 
cause segments to be deleted from the storage system after they 
have been replaced or added to an archive segment. The force 
feature can be used in conjunction with deletion to cause the 
safety function to be bypassed. (This is analogous to the 
operation of the deleteforce command.) This form of deletion 
should not be confused with the operation which deletes 
components from archive segments. 

The update feature causes components of archives to be 
replaced only if the date-time modified of the segment in the 
storage system is later than that associated with the component 
in the archive. If a component requested for updating is not 
found in the archive, it is not added to the archive. 
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The append feature can be used during replacement when 
additions only are to be made. If the archive command finds a 
component already present in the archive segment, a diagnostic is 
printed and replacement is not performed. 

The archive command can operate in two modes: if no 
components are named on the command line, the requested operation 
is performed on all components of the archive; if components are 
named on the command line, the operation is performed only on the 
named components. 

The star convention can be applied to the archive segment 
path name during the extraction and table of contents operations; 
it cannot be used during replacement and deletion operations. 
Component names may not be specified using the star convention. 

No commands other than archive/ archi ve_sor t, and 
reorder_archi ve should be used to manipulate the contents of 
archive segments; using a text editor or other similar commands 
will result in unspecified behavior. 



Usage 



archive key archivepath pathJL 



pathn 



1) key 



s one of the following: 



J&y. Function Comments 
Table of Contents Operations 



pr i nt lable of 
contents 



prints the entire table of contents if 
no components are named by the pathl 
arguments; otherwise it prints 

information about the named components 
only; a title and column headings are 
printed before the first listed 
component. 



tl print .table of 
contents in 
long form 

tb pr i nt .table of 

contents, briefly 

tlb pri nt lables of 
contents i n long 
form, briefly 



operates like t, printing 
information for each component. 



all 



Operates like t, except that the title 
and column headers are suppressed. 

Operates likes tl, except that the 
title and column headers are 
suppressed. 
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Replacement Operations 
r replace 



rd .replace and 
d.el ete 



rdf .replace and 
deletefprce 



cr jcppy and 
repl ace 



crd .copy, .replace, 
and .delete 

crdf .copy, replace, 
and deletefprce 

Append operations 

a append 



ad append and delete 



adf append and 
d.el etefprce 



replaces or adds components in the 
archive. If no component names are 
given, all components of the archive for 
which segments by the same name are 
found in the user's working directory 
are replaced. When components are 
named, if they are found in the existing 
archive segment, they are replaced by 
segments in the storage system; 
otherwise they are added. 

operates like r and deletes all segments 
which have been placed in the archive 
after the archive has been updated. 

operates like r and forces deletion of 
all replaced segments after the archive 
has been updated. 



operates 1 i ke r, 
archive In the user 
instead of changing 
segment , 



placing the updated 
's working directory 
the original archive 



operates like rd, placing a copy in the 
user's working directory. 

operates like rdf, placing a copy in the 
user's working directory. 



appends named components to the archive 
segment. If any named component is 
found within the archive, a diagnostic 
is issued and the component is not 
replaced. At least one component must 
be named by the pathl arguments. 



operates 
segments 
updated . 



like a and deletes all appended 
after the archive has been 



operates like a and forces 
al 1 appended segments after 
has been updated. 



deletion of 
the archive 
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ca £opy, append 



cad copy, append, 
and delete 



cadf c_opy, append, 

and deletefprce 



Update Operations 
u update 



ud update and 
a!el ete 



udf update and 
del etefprce 

cu c_opy and update 



cud copy, update, and 
delete 

cudf cjDpy, update, and 
d.el etefprce 

Deletion Qperat i ons 
d delete 

cd jtopy, delete 



1 ] j(ec 

archive segment 
di rectory. 



placing the 



k = =--^ new 
in the user's working 



operates like ad, placing the new 



archive segment in 
di rectory . 



the user's working 



operates like adf, 
new archive segment in 
working directory. 



placing the 
the user's 



operates like r except it replaces only 
those components for which the 
corresponding segment has a date-time 
modified later than that associated with 
the component found in the archive. If 
the component is not found in the 
archive, it is not added to the archive 
segment * 

operates like u and deletes all updated 
segments after the archive has been 
updated . 

operates like u and forces deletion of 
all updated segments. 

operates like u, placing the new archive 
in the user's working directory. 

operates like ud, placing the new 
archive in the user's working directory. 

operates like udf, placing the new 
archive in the user's working directory. 



deletes from the archive those 
components specified by arguments. 



operates like d, 
updated archive in 
di rectory. 



placing the 
the working 
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xf .extract and 
d.el etefprce 



2) archivepath 



Extraction Operations 

x .extract extracts from the archive those 

components specified by arguments/ 
placing them in segments in the storage 
system, as specified by the path name 
arguments. The mode stored in the 
archive is given to the segment for the 
user performing the extraction. Deletes 
segments if already present/ observing 
the duplicated name convention in a 
manner similar to the copy command. If 
no component names are given/ it 
extracts all components/ placing them in 
the working directory. The archive 
segment is not modified. 

operates like x, deleting or removing 
names from any segments found where the 
new segment is to be created. 

is the path name of the archive segment 
to be created or manipulated. The 
suffix ".archive" will be added if the 
user does not supply it. If the segment 
does not exist/ it will be created for 
replace or append operations. The star 
convention may be used for extraction 
and table of contents operations. 

specifies the components to be operated 

on for table of contents and deletion 
operations. For replacement and 

extraction operations/ it specifies the 
path name of a segment corresponding to 
a component whose name is the entry name 
portion of the path name. The star and 
equal conventions may not be used. 

Notes 

Each component of an archive segment retains certain 
attributes of the corresponding segment in the storage system. A 
single name, the effective mode of the user who placed the 
component in the archive/ the date-time the segment was last 
modified/ and the bit count of the segment are maintained. In 
addition/ the date-time that the component was placed in the 
archive segment is maintained. When a component is extracted 
from an archive segment and placed in the storage system/ the new 



3) pathi 
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segment is given the mode associated with the archive component 
for the user performing the extraction, the name of the 
component, and the bit count associated with the component. 

The archive command maintains the order of components 
contained within an archive segment. When new components are 
added, they are placed at the end. 

The archive command automatically creates an archive segment 
during replacement operations when no original archive exists. 

The archive command cannot be used recursively. Internal 
consistency checks are made to prevent the misuse of the command 
in this fashion. The user is asked a question if the command 
detects an attempt to use the archive command prior to its 
completing the last operation. 

During the operation of the archive command for replacement 
or deletion, because the replacement operation is not 
indivisible, it is possible for the updating operation to be 
stopped before it has been completed and after the original 

segment has been truncated. This may happen, for example, if a 
record quota overflow is received. When this situation occurs, a 
message is printed informing the user what has happened. In this 
case, the only good copy of the updated archive segment will be 
contained in the process directory. 

Archive segments may be placed as components inside of 
archive segments, preserving their identity as archives, and then 
later may be extracted intact. 

When the archive command detects an internal consistency 

error, it prints a status message and stops performing the 
requested operation. For table of contents and extraction 
operations, it will have completed requests for components 
appearing before the place where the format error is detected. 

For segment deletions after replacement requests, if the 
specified component name was a 1 i nk to a segment, the segment 
linked to is deleted. 

No more than thirty-two components may be named for any one 
request. For replacement operations where no components are 
named, more than thirty- two components may be replaced or 
appended, but if deletion is requested, only the first thirty-two 
segments will be deleted. A message is printed when this 
s i tuat i on occurs . 

The archive command observes the protected segment 
convention by interrogating the user when appropriate. 
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Name : arch i ve_scr t, as 

This command is used to sort the components of an archive 
segment. The components are sorted into ascending order by entry 
name using the standard ASCII collating sequence. The original 
archive segment is replaced by the sorted archive. 

Usage 

archive_sort pathi. .... pathn. 

1) pathi is the path name of an archive segment to be sorted. 
(The user need not supply the ".archive" suffix.) 

Notes 

There may be no more than 1000 components in an archive 
segment which is to be sorted. 

Storage system errors encountered while attempting to move 
the temporary sorted copy of the archive segment back into the 
user's original segment will result in diagnostics, and the 
preservation of the sorted copy in the user's process directory 
(telling the user its name). If the original is protected, the 
user will be interrogated to determine whether or not it should 
be overwritten. 
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Name : basic 

The basic command invokes the BASIC compiler to translate a 
segment containing BASIC source code. If the compile option is 
not specified, the compiled code is then executed. 



Usage 



basic source_name -optionl- 



-opt ionn- 



1) source__name 



2) optionl 



is the path name of the segment to be 
translated. The characters .basic may or may 
not appear as part of the path name. They 
must appear, however, on the segment itself. 

is selected from the following list of 
options. The options may appear in any 
order. 



-time n, -tm n 



-compi 1 e 



-library, -lb 



specifies a time limit of n. CPU seconds where 
n is an integer. When the time limit is 
exceeded, execution stops, and the user is 
asked if he would like to continue execution. 
If he answers yes, a new timer is set giving 
the user the same amount of time. 

indicates to compile the program and produce 
an object segment rather than immediately 
executing the code. The compiled object 
segment is saved in the user's working 
directory with the characters .dobj appended 
in place of .basic. The object segment is 
not a Multics standard object segment and can 
only be executed using the basic_run command. 

indicates that the Dartmouth library is to be 

segment. No other 



searched for 
di rectory i s 



the source 
searched. 



Notes 



This implementation of BASIC is described in BASI C , Sixth 
Edi t ion , published in 1971 by the Kiewit Computation Center, 
Dartmouth College, in Hanover, New Hampshire. 

The following is a list of differences between the Dartmouth 
and Multics implementations of BASIC: 
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1) The Multics storage system conventions differ from those 
at Dartmouth. Therefore/ if a user refers to a segment 
as 

20 file #l: n alpha" 

Multics will search for a segment named alpha in the 
user ! s working directory. If alpha is not found, the 
directory is searched for alpha. basic. If this is not 
found, the segment alpha is created. 

2) The number sign (#) must be entered with an escape 
character preceding it to avoid the Multics 
interpretation as an erase character. The upward arrow 
character is entered as a circumflex on Multics. 



The current version of the BASIC compiler is 
a proprietary program of Dartmouth College. 
It has been made available to users of the 
M.l.T. Information Processing Center with the 
permission of Dartmouth College. The BASIC 
compiler may not be used at other computer 
installations without permission of Dartmouth 
Col lege. 
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Name : basic_run, br 



This command will execute an object segment created by the 
BASIC compiler. For information on the BASIC language, see the 
write-up on the "basic" command in the MPM. 

Usage 



basic__run pathname -option!.- ... -optionn- 



1) pathname 



is the path name of the object segment to be 
executed. The characters ".dobj" may or may 
not appear as part of the path name but must 
be the last component of the BASIC object 
segment . 



2) optionl 



is selected from the following list 
options which may appear in any order: 



of 



-t ime n, -tm n 



specifies a time limit of n. CPU seconds where 
jn is an integer. When the time limit is 
exceeded, execution stops, and the user is 
asked if he would like to continue execution. 
If he answers yes, a new timer is set giving 
the user the same amount of time. 



-1 i brary, -lb 



indicates that the Dartmouth library is to 
be searched for the object segment. No other 
directory is searched. 



The current version of the BASIC compiler is 
a proprietary program of Dartmouth College. 
It has been made available to users of the 
M.l.T. Information Processing Center with the 
permission of Dartmouth College. The BASIC 
compiler may not be used at other computer 
installations without permission of Dartmouth 
Col 1 ege . 
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Name : bas i c_system, bs 

bas ic__system is the standard BASIC source editor and run 
dispatcher. A BASiC source segment path name must be specified. 
If the segment exists, it is picked up; otherwise a new segment 
is expected to be input. 

This is an interactive BASIC, as opposed to the Multics 
"basic" command, which only compiles a program. 

Usage 

basic_system pathname 

1) pathname is the path name of an existing or a to be created 
segment. The .basic suffix is assumed. 

Requests 

The bas i c_system editing requests are: 

line number basic source line 

adds or replaces a basic source line in proper 
sequence. The line number must be less than 
10,000. 

line number deletes that source line if such a line number 
exists. 

save stores the current internal source segment in the 

segment specified in the command line. 

quit returns from bas i c_system. The current internal 

segment is lost. 

list prints the entire current internal segment. 

run calls BASIC with the current internal source 

segment . 

Any other type of request is ignored. 
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Notes 



If you quit out of a BASIC compilation or execution run / 
immediately issue the prograrrM nter rupt (pi) command in order to 
get back to bas i c_system. Otherwise, any unsaved BASIC program 
within bas i c__system will be lost. 

Refer to BASIC , Fifth Edi t ion , published by the Kiewit 
Computation Center, Dartmouth College, Hanover, New Hampshire, 
September 1970, for detailed information on the BASIC language 
syntax . 



The current version of the BASIC compiler is 
a proprietary program of Dartmouth College. 
It has been made available to users of the 
M.l.T. Information Processing Center with the 
permission of Dartmouth College. The BASIC 
compiler may not be used at other computer 
installations without permission of Dartmouth 
Col 1 ege e 
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Name : bind, bd 



This is the command interface to the Multics binder which, 
given one or more separately translated procedure object 
segments, produces a single inclusive and compact bound procedure 
object segment. The bound segment will be in standard object 
segment format if all input segments are standard object 
segments. (See the MPM Subsystem Writers 1 Guide section, The 
Multics Standard Object Segment.) This write-up describes 
version 8.1 of the binder: 



Usage 



bind arcl ... arcn — update- -upd.1- ... -updn- -control__arg 



1) arcl is the pathname of an archive segment 

containing one or more component object 
segments to be bound. Up to 16 (current 
arbitrary implementation limit) input archive 
segments may be specified. They are logically 
concatenated in a left to right order to 
produce a single sequence of input component 
object segments. The specified pathname of the 
archive segment may or may not contain an 
explicit .archive suffix. 



2) -update, -ud is an optional functional argument to the 

binder indicating that the following list of 
archive segments (updj.) specifies update rather 
than input object segments. (See below.) 



3) updi is the pathname of an optional archive segment 

containing update object segments. Up to a 
combined total of 16 input and update segments 
may be specified. The contained update object 
segments are matched against the input object 
segments by object segment name. Matching 
update object segments replace the 
corresponding input object segments; unmatched 
ones are appended to the sequence of input 
object segments. If several update object 
segments have the same name, only the last one 
will be bound. 



k) control_arg the bind command accepts either of the 

following two optional control arguments: 

-list, -Is produces a listing segment whose name is 
derived from the name of the bound object 
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segment plus a ".list" suffix. The listing 
segment is generated for the purpose of 
dprinting, and contains the bound segment's 
.bind control segment/ its bind map, and that 
information from the bound object segment which 
would be printed by the pr int_l ink__info 
command. See the MPM write-ups for dprint and 
pr i nt_l ink_info. 

-map produces a .list listing segment which contains 

only the bind map information. 

In the absence of either of these control 
arguments, no listing segment is generated. 

IhSi Bindfile 

As is discussed in more detail in Syntax of the Bi ndf i le 
below, special binding instructions may be provided in symbolic 
form in a special ASCII segment known as the bindfile whose entry 
name must contain the suffix ".bind". The bindfile must be 
archived into any one of the input archive segments (at any 
location within that archive segment) where it will be 
automatically located and recognized by the binder. 

In the case in which two bindfiles are specified, one in an 
input archive segment and the other in an update archive segment, 
the latter takes precedence and an appropriate message is printed 
to that effect. 

Output 

The binder produces as its output two segments: an 
executable bound procedure object segment and an optional 
printable ASCII listing segment. The name of the bound object 
segment is, by default, derived from the entry name of the first 
input archive segment encountered by stripping the .archive 
suffix from it. The name of the listing segment is derived from 
the name of the bound segment by adding to it the .list suffix. 
Use of the Objectname master statement in the bindfile (see 
Master Kev Words below) allows the name of the bound object 
segment to be stated explicitly. In addition, use of the Addname 
master statement in the binding instructions (as explained below) 
will cause additional segment names to be added to the bound 
segment. Note that the primary name of the bound object segment 
must not be the same as the name of any component, since both the 
bound object name and the component names must be stored in the 
definition section. 
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BacKsround Information 

In order to understand the purpose of the bindfile, some 
knowledge of the binder's functions is required, 

A Multics procedure object segment consists of an internal 
part (pure text/ internal static, and symbol table) which is the 
machine code representation of the source program, and an 
external part (definition section and linkage information) which 
defines certain external variables by a symbolic name for the 
purpose of dynamic i nterprocedure linking. 

The binding process performs two distinct operations: a) a 
bound object segment is produced whose internal part (i.e., text, 
internal static, and symbol table) is a concatenation of the 
respective (relocated) portions of the component object segments; 
and b) all interprocedure references among the bound component 
object segments are prel inked at bind time. 

The external part of the bound segment is newly generated to 
reflect the bound object segment's interface with the external 
world. Many external symbols previously defined within the 
component objects may now be internal to the bound object segment 
and need, therefore, no longer be defined as external to it. 

The binder performs its internal prelinking by establishing 
direct text-to-text or text-to-internal static references among 
the bound component objects. For nonstandard object segments, 
dynamic links to procedure entry points are established through 
an indirect entry sequence located in the entered procedure's 
linkage section. The purpose of this indirection is to properly 
reload the linkage pointer (LP) register before the procedure 
itself is entered. The binder dispenses with this indirection in 
its internal prelinking because the entire bound object segment 
requires a single value of LP which has been set properly when 
the bound object was first entered. Under certain circumstances, 
however, it is customary in Multics to pass entry values to 
external procedures (e.g., condition,,, i pc_$decl_ev_cal l__chn ) 
which later may invoke the entry specified by such an entry 
value. If such an entry value refers to an entry point which is 
internal to the bound segment, but which is not internal to a 
component originally in standard object segment format, that 
entry point's indirect entry sequence in the linkage section must 
be regenerated to assure that a transfer of control to that entry 
point will cause the LP to be reloaded properly. 

The main purpose of the bindfile is to specify which 
external symbols within the component objects are to be retained 
in the bound objects, which are to be deleted, and which are to 
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be prel inked indirectly through an entry sequence in the linkage 
section because they are used as parameters in calls to 
procedures such as condi t ion__ or i pc_$decl_ev__cal l_chn . 

Syntax o_f Bindf i le 

The binder's symbolic instructions have their own syntax 
which allows for statements consisting of a key word followed by 
zero or more parameters and then delimited by a statement 
delimiter. Master statements pertain to the entire bound object 
segment/ regular statements pertain to a single component object 
within the bound object segment. Master statements are 
identified by master key words which are distinct from regular 
key words in that they begin with a capital letter; regular key 
words begin with a lower case letter. A key word designates its 
parameters and a certain action to be undertaken by the binder 
pertaining to those parameters. 

Following is a list of the delimiters used: 



key word delimiter. It is used to identify a 
key word followed by one or more parameters. 
A key word which is followed by no parameters 
is delimited by a statement delimiter. 



statement delimiter. 



parameter delimiter (the last parameter is 
delimited by a statement delimiter). 



/* 



begin comment. 



*/ 



end comment. 



Normal Ke_y_ Words 



ob jectname 



the single parameter is the name of a 
component object as it appears in the archive 
segment. The objectname statement indicates 
that all following normal statements (up to 
but not including the next objectname 
statement) pertain to the component object 
whose name is the parameter of the objectname 
statement. 



synonym 



the parameters are symbolic segment names 
declared to be synonymous to the component 
object's objectname. The synonym statement 
has two uses. First, it facilitates the 
Multics linker's lookup of entries in bound 
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segment components that have several external 
segment names associated with them. Second, 
it allows the binder to locate the component 
object, for the purpose of prel inking, even 
if it is referenced by names other than its 
objectname. Users should take care to state 
explicitly in a synonym statement all the 
normally used segment names of a component 
object. For example, the commands list, 
listnames and listtotals are all implemented 
in one procedure, and all have 
abbreviations; thus a bindfile for the bound 
segment in which this procedure resides would 
contain : 

objectname: list; 

synonym: Is, listnames, In, listtotals. 

It; 

Failure to state segment names results in 
most inefficient linker performance. 

retain the parameters are the symbolic names of 

external symbols (i.e., entry names and 
segdefs) declared within the component object 
segment which the user wishes to retain 
(i.e., have regenerated) as external symbols 
of the bound object segment. 

delete the parameters are the symbolic names of 

external symbols (i.e., entry names and 
segdefs) declared within the component object 
segment which the user does not wish to be 
regenerated as external symbols of the new 
bound segment. 

indirect the parameters are the symbolic names of 

entry names (no segdefs) of the component 
object segment which are to be prel inked 
indirectly through a regenerated entry 
sequence in the bound segment's linkage 
section. For components not in standard 
object segment format, an indirect statement 
must be specified for all entry points used 
as parameters in calls to procedures such as 
condition^ and i pc_$decl_ev_cal l_chn . 
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nol ink 



global 



The retain / delete and indirect statements 
are considered to be exclusive. An error 
message is displayed if the binder recognizes 
that two or more such statements were made 
regarding any single external symbol. 

the parameters are the symbolic names of 
external symbols which are not to be 
prelinked during binding; i.e., all 
references to such symbolic names will be 
regenerated in the form of links to external 
symbols. The no_Jink statement implies a 
retain statement for the specified symbols. 

the global statement may have as its 
parameter either retain, delete, indirect or 
no__link which becomes effective for all 
external symbols of the component object. An 
explicit retain, delete, indirect or no__link 
statement concerning a given external symbol 
of the component object overrides the global 
statement for that specific external symbol. 
A global no_link causes all external 
references to the component object to be 
regenerated as links to external symbols, to 
allow execution time substitution of such a 
component by a free standing version of it, 
for example for debugging purposes. 



table 



does not require parameters. It causes the 
symbol table for the component to be retained 
and is needed to override the master key 
word No_Table, which is described below. 



Master Key Words 
Obj ectname 

Order 



the parameter 
bound object. 



is the segment name of the new 



the parameters are a list of objectnames in 
the desired binding order. In the absence of 
an order statement, binding will be done in 
the order of the input sequence. The order 
statement requires that there be a one-to-one 
correspondence between its list of parameters 
and the components of the input sequence. 



Force_Order 



same as Order, except that 
parameters may be a subset 
sequence, allowing the archive 



the list of 
of the input 
segments to 
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contain additional segments which are not to 
be bound (e.g./ source programs). 

is the same as the global statement except 
that it pertains to all component object 
segments within the bound segment. A global 
or explicit statement concerning a single 
component object or a single external symbol 
of a component object overrides the Global 
statement for that component object or 
symbol. 

the parameters are the symbolic names to be 
added to the bound segment. If Addname has 
no parameters/ it causes the segment names 
and synonyms of those component objects for 
which at least a single external symbol was 
retained to be added to the bound object 
segment. 

does not require parameters. It causes the 
symbol tables from all the component symbol 
sections containing them to be omitted from 
the bound segment except when they are needed 
by (version II) PL/I I/O runtime routines. 
If this key word is not given, all symbol 
tables will be kept. 

If no bindfile is specified, the binder assumes default 
parameters corresponding to the following: 

Objectname: segment name of the first input archive file. 

Global: retain; /*regenerate all definitions*/ 

Error Messages 

The binder produces three types of error messages. Messages 
beginning with the word "Warning:" do not necessarily represent 
errors. Messages beginning with the word "binder_:" normally 
represent errors in the input components. Errors detected during 
the parsing of the bindfile have the format: 

Bindfile Error Line #n .... 

where n. is the line number of the offending statement, , to allow 
easy retrieval through use of a context editor. If one of the 
latter occurs the binder aborts, as it would not be able to bind 
according to the user's specifications. 



Global 



Addname 



No Table 
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The message 

"binder_: Fatal error has occurred; binding unsuccessful." 

indicates that due to errors detected during binding it was 
impossible for the binder to produce an executable object 
segment. The bound object segment is left in an unpredictable 
state. 



The binder may be considered, in some sense, to be a 
language processor whose source language is the collection of 
component object segments. For components not in standard object 
segment format, it has to be cognizant of the code generation 
peculiarities of the diverse translators supported by Multics. 
Therefore, before processing a component object segment, it looks 
up, in the component's symbol table, the name of the processor 
which produced that component object segment. If that component 
is not in standard format and if that language processor is 
unknown to the current version of the binder, it will display an 
error message and refuse to handle that component object. 
Binding is terminate at that point. 

Also, because the binder does not preserve the original 
linkage section of the component object segment, code which makes 
assumptions about the existence of a given link in the linkage 
section (i.e., which would cease to work if that link were 
removed by the binder), or which assumes a certain structure of 
links (i.e., an array of links used as a transfer vector and 
accessed through indexing) is not bindable by the Multics binder 
and will normally result in a display of an appropriate error 
message or, occasionally, in unpredictable results during the 
execution of the bound segment. 



Notes 
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Examples 

Following are examples of bindfiles. 
1) Bindfile for aim — bound_alm__. bi nd 



Global : 



delete; 



object name: aim; 
retain: aim; 



/♦delete all old definitions*/ 
/♦retain definition for single entry*/ 



2) Bindfile for debug bound__debug_.bi nd 

Global: delete; /*delete all old definitions*/ 

Addname; /♦add names debug, db, list_arg_ 

and gr_print to bound segment 
bound_debug_*/ 



objectname: debug; 



synonym: 
retain : 



indi rect : 



db; 

debug, 
db; 

fault; 



/♦indicate db is synonymous to debug*/ 

/♦retain entry names debug$debug and 

debug$db^/ 
/♦indirect entry sequence for condition 

handler debug$f aul t*/ 



objectname : 
retain: 



1 ist_arg_; 

list_arg_; /♦retain entry name 1 i s t_arg_$ 1 i st__arg_V 
objectname: gr_print; 

retain: gr_print; /♦retain entry name gr_pr i nt$gr_pr int*/ 



0 Copyright, 
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Name ; calc 

The calc command provides the user with a calculator capable 
of evaluting arithmetic expressions with operator precedence, a 
set of often-used functions, and an addressable-by-identifier 
memory. 

Usage 

calc 

initiates the command. The user may then type in any number of 
expressions, assignment statements, list commands, or a quit 
command, separated from each other by one or more carriage 
returns . 

Expressions 

Arithmetic expressions involving real values and the 
operands +, -, *, /, and ** (addition, subtraction, 
multiplication, division, and exponentiation) may be typed in. 
Prefix plus and minus are allowed. Parentheses may be used, and 
blanks between operators and values are ignored. Calc will 
evaluate the expression and print out the results. For example, 
if the user typed: 

2 + 3*1* 

calc would respond: 

lk 

The order of evaluation is as follows: 

1) expressions within parentheses 

2) function references 

3) prefix +, prefix - 
k) ** 

5) *, / 

6) +, - 
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Operations of the same level are processed from left to 
right/ except for the prefix plus and minus which are processed 
from right to left. Note that this means that 2**3**1* is 
evaluated as (2**3)**^. 

Numbers may be integers (123)/ fixed point (1.23) and 
floating point (1.23e+2/ 1.23e2/ 1.23E2/ or 1230E-1). All are 
stored as float bin(27). An accuracy of about seven figures is 
maintained. Variables (see below) may be used in place of 
constants; e.g./ pi * r ** 2. 

Seven functions are provided: sin, cos, tan, atan, abs. In, 
and log (In is base e, log is base 10). They may be nested to 
any 1 evel : 

sin(ln(var)*45*pi/180) 

Ass i gnment Statement 

The value of an expression may be assigned to a variable. 
The name of the variable must be 1 to 8 characters in length/ and 
must be made up of letters (upper and/or lower case) and the 
underscore character (_) . The form is: 

<var i abl e>=< express i on> 

For example/ the following are legal assignment statements: 

x = 2 

Rho = sin(2*theta) 

The calc command does not print any response to assignment 
statements, "pi" and "e" have pre-assigned values of 3.1^159265 
and 2.7182818/ respectively. 

-»>» 

List Command 

If "list" is typed calc will print out the names and values 
of all the variables that have been declared so far. 

Qui t Command 

Typing "q" will cause calc to return to the calling program; 
i.e. to command level. 
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Exampl es of Use 



user: calc 
2+2 

calc: = h 
u: r = 1.5 

pi *r**2 
c: = 7.068583 

u: sin(O.Ol) 
c: = 9.999832E-3 

u: 143ell+(12el3 
c: too many ( 

u: U3ell+(12el3) 
c: = 1.343E+U 

u : list 
c: 

r - 1.5 
e = 2.718282 

pi = 3.11*1592 
u : q 



(c) Copyright, 1973, Massachusetts Institute of Technology 

and Honeywell Information Systems Inc. (END) 



MULT ICS PROGRAMMERS 1 MANUAL 



cancel __abs_request 



Command 
Development System 
9/22/71 



Name : cancel_abs_request, car 

The cance l_abs_reques t command allows a user to delete a 
request for an absentee computation which is no longer required. 
Normally the deletion can be made only by the user who originated 
the request. 



Usage 



cancel_abs_request pname -optionl- 



-opt ionn." 



1) pname 



2) optionj. 



is the pathname of the absentee control 
segment associated with this request. The 
pathname must be typed as it was given in 
the original request. 



is selected from 
options and may 
command 1 ine: 



the following list of 
appear anywhere on the 



-queue n., -q H 



-all, -a 



-brief, -bf 



NotQS 



indicates which priority queue is to be 
searched. It must be followed by an 
integer specifying the number of the 
queue. If this option is omitted, the 
third priority queue is searched unless 
the -all option is provided. (See below.) 

indicates that all priority queues are to 
be searched starting with the highest 
priority queue and ending with the lowest 
priority queue. 

indicates that the message "Absentee 
request pname cancelled" is omitted. 



The last request for an absentee computation is deleted if 
there is more than one request associated with the same absentee 
control segment in the same queue. 

If the request refers to an absentee process which is 
already logged in, this command will not be effective in stopping 
the absentee computation. 
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Fxampl e 

car >udd>Mul t i cs>Jones>dump>transl ate 

would delete the last absentee request which the user had made in 
queue 3 that was associated with the control segment 
>udd>Mul t i cs > Jones >dump> trans 1 ate .abs i n . 
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Name : cancel _daemon__request / cdr 

The cancel_daemon_request command allows a user to delete a 
dprint or dpunch request which is no longer required. Normally 
the deletion can be made only by the user who originated the 
request. See the MPM command write-ups for dprint and dpunch. 



Us_a&£. 



cancel_daemon_request pname -ctl_argl.- 



-ctl_argn- 



1) pname 



2) ctl_argi 



is the path name of the segment for which 
the dprint or dpunch request is to be 
cancelled. The path name must be typed 
exactly as it was given in the original 
request. 

is selected from the following list of 
control arguments and can appear anywhere 
in the command line: 



-queue n, -q n 



indicates which priority queue is to be 



-all/ -a 



-brief/ -bf 



searched. It must 
integer specifying 
queue. If this 
omitted/ the third 
searched unless the 



be fol lowed by an 
the number of the 
control argument is 
priority queue is 
-all control argument 



is provided. (See below.) 

indicates that all priority queues are to 
be searched starting with the highest 
priority queue and ending with the lowest 
priority queue. 

indicates that the message "Dprint 
(dpunch) of pname cancelled" is to be 
omi tted. 



Notes 

The last request to print or punch a segment is deleted if 
there is more than one request associated with the same user for 
that segment in the same queue. 

If the request refers to a segment which the I/O daemon is 
already processing/ this command is not effective in stopping the 
print or punch operation. 
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Example 

cance l_daemon_request >Jones_di r>dump> trans 1 ate . 1 i st 

would delete the last request which the user had made in queue 3 
to print or punch the segment >Jones_d i r>dump> trans late, 1 i st . 
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Standard Service System 
02/16/71 



Name : change_ def au 1 t__wdi r, cdwd 

The change_ def aul t_wdi r command records a specified 

directory as the user's default working directory during the 

duration of the current process or until the next 
change_def au 1 t_wdi r command is issued. 



Usage 

change__def au 1 t_wdi r -path- 

1) path is the directory which is to become the default working 
directory. If path is not given, the current working 
directory becomes the default working directory. 



Notes 



The change_def au 1 t_ wdi r command is used in conjunction with 
change_wdi r . When the change_wdir command Is issued with no 
arguments, the default working directory becomes the current 
working directory; if no default working directory has been 
established, the change_wdir command prints an error message. 

See also change_wdir and pr i nt_def aul t_wdi r in the MPM. 
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Name : change_error_mode, cem 

This command is used to control the amount of information 
printed by the default error handler. It affects all the 
messages for the life of a process or until it is invoked again. 



Usag e 



change_error_jnode -option- 



1) option may be chosen from the following list of 

options: 

-brief, -bf prints the condition name. 



long/ -lg prints more complete messages. In 
particular, if a segment is bound, both the 
offset relative to the procedure and the 
offset relative to the segment are printed. 
When there is a crawl out, both sets of 
machine conditions are printed. 



Note 

The normal mode, with the message intermediate in length 
between the brief and long messages, is the default, and can be 
reset by giving this command with no arguments. 
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Name : change__wdi r, cwd 

The change_wdir command changes the user's current working 
directory to the directory specified as an argument. 

Usage 

change__wdir -path- 

1) path is the pathname of the directory to change to. If path 
is not given^ the default working directory is assumed. 

Notes 

If path specifies a nonexistent directory, an error message 
will be pr in ted. 

No access to path is required for the command to be 
employed. However, once the working directory has been changed, 
the user can proceed only according to his access to path. That 
is, to effectively use path as a working directory, he must have 
a mode of "rewa" for path. Restricted uses are possible in 
accordance with the mode attributes on the directory. For 
example, the mode must be at least "r" to list the directory. 

See also change_def aul t_wdi r and pr i n t_def au 1 t_wd i r in the 

MPM. 
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Name : check_i nf o_segs, cis 

The check_i nfo_segs command prints a list of new or modified 
segments. It saves the current time in the user profile, so that 
when it is invoked again, it lists segments created or modified 
since the last invocation. 

Optional control arguments allow check_i nf o_segs to be used 
to perform a specified command on each modified segment, or to 
search any directory for modified segments, or to use a time 
other than that of the last invocation for the comparison. 

Usage 

check_i nf o_segs -con t rol_a rgs- 

1) control_args can be selected from the following: 

-date string, -dt string If this argument is given, 

check_i nfo_segs uses the date 
specified by string instead of the 
date in the user profile, string 
must be acceptable to the 
convert_date_to_bi nary_ subrout ine. 
(See the convert_date_to_b i nary_ 
write-up in the MPM.) The time of 
last invocation in the user profile 
is not updated to the current time. 

If this argument is specified, 
check__i nfo__segs lists the date and 
time modified as well as the name of 
any segment selected. 

If this argument is specified, 
check_J nfo_segs does not print the 
names of selected segments and 
suppresses the comment "no change" 
if no segments are selected. This 
argument is intended for use with 
the -call control argument described 
be 1 ow . 

If this argument is specified, 
check_info__segs does not place the 
current time into the user profile. 



-long, -lg 



-brief, -bf 



-no_update, -nud 
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-call cmdline If this argument is specified/ 

check_J nfo_segs calls the current 
command processor with a string of 
the form "cmdline path" for each 
selected segment/ after the name of 
the segment is typed, path is the 
absolute pathname of the segment. 
Note that cmdline must be enclosed 
in quotes if it contains blanks. 

-pathname path/ -pn path If this control argument is 

specified/ check__i nfo_segs assumes 
that path is a pathname with one or 
more asterisks in the entryname 
portion. All new or modified 
segments that match path are 
selected. 

Up to 10 occurrences of this 
argument can appear in a call to 
check_i nf o_segs . All specified 
directories are searched/ in the 
order that the arguments were given. 
If the -pathname control argument is 
not specified/ the defaults are 
>documentat ion> i nf o>* . i nfo and 
>documentat ion> iml_i nfo>* . info. 

Notes 

The first time check_i nf o__segs is invoked by a particular 
user/ it just initializes the time in the user profile to the 
current time/ prints a comment/ and does not list any segments. 
If a profile does not exist/ it is created. 

check_i nfo_segs checks the time modified for any segment 
pointed to by a link/ not the time the link was modified. The 
command types a warning message if any segment pointed to by a 
1 i nk does not ex i st . 

The check_i nf o_segs command cannot detect that a segment has 
been deleted since the last invocation of the command. 
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Samples 

1) Check for info segments modified since the specified date: 

check_info_segs -date "07/01/73 0900." 

2) Print all modified info segments: 

check__i nfo_segs -call print -bf 

Note that the "-bf" argument is given to check_i nf o_segs to 
suppress duplicate printing of segment names since the print 
command types the segment name in the heading. 

3) Print just the first block of any modified info segment: 

check_i nf o_segs -call "answer no help -pn" 

Note that the -pn argument must be given to the help command, 
since check_J nf o_segs supplies an absolute path name as the 
other argument in the command line. 

k) Check for all modified info and peruse__text segments: 

cis -pn >doc>pt>*.pt -nud 
c i s 

Note the use of the -nud argument to prevent the time of last 
invocation from being updated in the first command line. 
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Name : close_fiie/ cf 

The close__file command closes specified FORTRAN and PL/ 1 
files. It closes all open files if the -all control argument is 
spec i f ied. 

Usage 

close_file -ctl_arg- -fil enamel- ... -filenamea- 

1) ctl_arg can have the value -all to close all open files. 

In this case, no filename! appears. 

2) filename! is the name of an open FORTRAN or PL/ I file. 
Notes 

The format of a FORTRAN file name is f ? lenn where no. i s a 
2-digit number other than 00; e.g., file05. PL/ I file names are 
selected by the user and can have any format. 

If a specified file cannot be found/ an error message is 
printed indicating the name of the file. The rest of the 
specified files are closed. 

For each filename!/ all PL/ I files of that name and/ if 
applicable/ the FORTRAN file of that name are closed. 
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Name ; code, decode 

In order to provide maximum security for data stored in a 
Multics segment, the code command Is provided to encipher a 
segment's contents according to a key which need not be stored in 
the system. The decode command, given an enciphered segment and 
the same key, reconstructs the original segment. The two 
segments, original and enciphered, have the same length. 

Usage 

To encipher: 

code namel -name2- 

1) namel is the path name of the segment to be enciphered. 

2) name2 is the path name of the enciphered segment to be 

produced. If name2 is not provided, it is taken 
to be the same as namel. This command always 
appends the suffix ".code" to name2 to produce the 
name of the enciphered segment. 

To decipher: 

decode namel -name2- 

1) namel is the path name of the enciphered segment. The 

".code" suffix should not be specified. 

2) name2 is the path name of the deciphered segment to be 

produced . 

Notes 

The code command requests an encipherment key (1-11 
characters not including space, semicolon, or tab) from the 
terminal. The printer is turned off while the key is typed. The 
command then requests that the key be typed again, to guard 
against the possibility of mistyping the key. If the two keys do 
not match, the key is requested twice again. 

The decode command requests the key from the terminal only 
once, and produces name2 from the enciphered segment namel. code. 
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jjajoe.: compare 

The compare command compares two segments and lists their 
differences. The comparison is a word-by-word check and can be 
made with a mask so that only specified parts of each word are 
compared. 



Usage 



compare pathl | of f setl path2 |of f set2 -ctl_argJL- -ctl_arg2.- 



1) pathl/ path2 



2) offsetl, offset2 



are the path names of the segments to be 
compared. The equal convention is allowed 
for path2. 

are octal offsets within the segments to be 
compared. The comparison begins at the word 
specified or with the first word of the 
segment if no offset is specified. 



3) ctl_argl 



specifies one of 
arguments : 



the following control 



-mask n 



specifies that the octal mask 
used in the comparison. If 
12 octal digits it is padded 
with zeros. 



jl is to be 
a is less than 
on the left 



-length a, -lg H 



specifies that the comparison should 
continue for no more than a (octal) words. 



Notes 

The actual number of words to be compared is the minimum of 
the control argument -length, the word count of the first segment 
minus its offset, and the word count of the second segment minus 
its offset. The word count of a segment is computed by dividing 
the bit count plus 35 by 36. If the word count minus the offset 
is less than zero an error message is printed and the command is 
aborted . 

The command lists any differences found in the following 
format: 



offset 
k 
6 



contents 
404000000002 
404000000023 



offset 
4 
6 



contents 
000777000023 
677774300100 
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To compare segments containing only ASCII character string 
data, use the compare_asc i I command described in the MPM. 
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Name : compare_asc i i , cpa 



This command compares two ASCII files and prints out the 
changes made to the file specified by oldpath to yield the file 
newpath. The output is organized with the assumption that the 
first file was edited resulting in the second file. 



usage 



compare_asci i oldpath newpath -nl- -n2- 



1) oldpath 

2) newpath 

3) nl 
h) n2 



is the pathname of the first file. 

is the pathname of the second file 
result of editing the first file). 



(the 



is a decimal number (optional) specifying the 
minimum number of characters which must be 
the same before compare_asc i i will assume the 
segments are again "in sync". 

is a decimal number (optional) analogous to 
nl specifying the minimum number of lines 
that must be the same. It is required that 
nl be specified to exercise this option. 



flotgs 

The equals convention may be used. If nl and n2 are both 
given, they must both be exceeded for the segments to be 
considered "in sync" again. 
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Standard Service System 
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Name : copy/ cp 

The copy command causes copies of indicated segments to be 
created in indicated directories wi th indicated names. Access 
control lists (ACLs) and multiple names are optionally copied. 

"sage 

copy pathll path21 ... pathln path2n -cal- ... -ca.Q~ 

1) pathll are the segments to be copied. 

2) path21 are the copies to be created. If the last path21 

is not given, the copy is placed in the working 
directory with the entry name of the segment from 
which it was copied. 

3) cal may be chosen from the following list of control 

arguments : 

-name/ -nm causes multiple names to be copied. 

-acl causes the ACL to be copied. 

-all/ -a causes multiple names and ACLs to be copied. 

-brief/ -bf causes the messages "Bit count inconsistent with 
current length..." and "Current length is not the 
same as records used..." to be suppressed. 

The control arguments may appear once anywhere in the 
command line and apply to the entire command line. 

Notes. 

Read access is required for pathll. Execute access is 
required for the directory containing pathll. Execute/ write, 
and append access are required for the directory containing 
path21. 

The star and equal conventions may be used. 

L&amals 

copy >ol d_di r>f red. 1 i st george.= 

The segment fred.list in the directory >old_dir is copied into 
the working directory as george.list. 
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Command 

Standard Service System 
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Name : create, cr 

The create command causes a storage system segment of 
specified name to be created in specified directory (or in the 
working directory). That is, it creates a storage system entry 
for an empty segment. See createdir for creation of directories, 
and link for creation of links. 

Usage 

create path! ... pathn 
1) pathx is the name of the segment to be created. 
Notes 

The user must have execute and append access for the 
directories in question. 

If the creation of a new segment would introduce a 
duplication of names within the directory, and if the old segment 
has only one name, the user will be interrogated as to whether he 
wishes the segment bearing the old instance of the name to be 
deleted. (If the old segment has multiple names, the conflicting 
name will be removed and a message to that effect issued to the 
user. ) 

The user is given rewa access to the segment created. 

All directories specified in pathj_ must already exist. That 
is, only a single level of storage system hierarchy can be 
created with one invocation of this command. 

Exampl e 

create f i rs t_cl ass_ma i 1 >new_di r >al pha>be ta 

would cause the segment f i rs t_cl ass__ma i 1 to be created in the 
working directory and the segment beta to be created in the 
directory >new_di r>al pha. A noted above, the directories new_dir 
and alpha must already exist. 
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Command 
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Name ; createdi r, cd 

The createdi r command causes a storage system directory 
branch of specified name to be created in a specified directory 
(or in the working directory). That is, it creates a storage 
system entry for an empty subdirectory. See the write-up of the 
create command for creation of segments. 

Usage 

createdir pathl ... pathjn 
1) pathj_ specifies the name of the subdirectory to be created. 
Notes 

The user must have append access for the directories in 
quest ion. 

If the creation of a new subdirectory would introduce a 
duplication of names within the directory, and if the old 
subdirectory has only one name/ the user is interrogated as to 
whether he wishes the subdirectory bearing the old instance of 
the name to be deleted. (If the old subdirectory has multiple 
names, the conflicting name is removed and a message to that 
effect issued to the user.) 

The user is given sma access for the subdirectory created. 

All higher-level directories specified in pathj_ must already 
exist. That is, only a single level of storage system hierarchy 
can be created with one invocation of this command. 

Example 

createdir sub >my_di r >al pha>new 

would create the subdirectory sub immediately inferior to the 
current working directory and the subdirectory new immediately 
inferior to the directory >my__di r>al pha. As noted above, the 
directories my_dir and alpha must already exist. 
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Name : debug, db 

The debug command is an interactive debugging aid to be used 
in the Multics environment. It allows the user to look at or 
modify data or code. The concept of breakpoints (commonly called 
breaks) is implemented and thus makes it possible for the user to 
gain control during program execution for whatever reason he may 
have. A concise syntax for user requests coupled with a complete 
system of defaults for unspecified items allows the user to make 
many inquiries with little effort. Symbolic references permit 
the user to retreat from the machine oriented debugging 
techniques in common use and to refer to variables of interest 
directly by name. 

debug uses a segment in the initial working directory to 
keep track of information about breaks. The segment is created 
if not found. If the segment cannot be created, the break 
features of debug are disabled and unusable. The name of the 
break segment is username. breaks where username is the login name 
of the user. 

lipase 

debug 

Notes 

The debug command provides the user with the following 



funct 


ions : 




1) 


i t 


can 


look at data or code; 


2) 


i t 


can 


modify data or code; 


3) 


it 


can 


set a break; 


k) 


i t 


can 


perform (possibly nonlocal) transfers; 


5) 


i t 


can 


call procedures; 


6) 


it 


can 


trace the stack being used; 


7) 


i t 


can 


look at procedure arguments; 


8) 


it 


can 


control and coordinate breaks; 


9) 


i t 


can 


continue execution after a break fault; 
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10) It can change the stack reference frame; 

11) it can print machine registers; and 

12) it can execute commands. 

These functions are provided by two types of debug requests: 
data requests and control requests. The first five functions 
above are performed by data requests; the others, by control 
requests. Several debug requests (either data or control) may be 
placed on a line separated by semicolons (;). 

Data Requests 

Data requests consist of three fields and have the following 
format : 

generalized address) <operator> <operands> 

The generalized address defines the actual data or code of 
interest. It is ultimately reduced to segment number and offset 
by debug before being used. The operator field indicates to 
debug which function to perform, e.g., print rather than modify 
the data referenced by the generalized address. The operands 
field may or may not be necessary, depending on the operator. 
When these fields are specified, they are separated by blanks or 
commas . 

As debug decodes a data request, it parses the generalized 
address and generates a pointer to the data being referenced. 
This pointer, called the working pointer, is changed whenever the 
generalized address is changed. It points into either the 
working segment, its stack frame, or its linkage section. The 
actual segment depends on the most recent specification in a 
generalized address. The form for a generalized address is as 
fol lows : 

t/segment name/3 Loffset] {segment ID] [relative offset] 

(The brackets are metalinguistic and are not in the debug 
syntax.) The segment name is either a path name, a reference 
name, or a segment number, and defines what is called the working 

segment. If the working segment is a procedure segment with an 
active stack frame, the stack frame may be referenced by 

specifying &s as the segment ID. If the working segment has an 
active linkage section (i.e., one with an entry in the Linkage 
Offset Table (LOT) for the working ring), this may be referenced 
by specifying &1 as the segment ID. A segment ID of &t refers to 
the working segment itself. 
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The offset field is used as an offset within the segment 
referenced by the working pointer. For the working segment/ this 
offset is relative to the base of the segment. If the working 
pointer points into an active stack frame, the offset is relative 
to the base of that frame. If the working pointer points into an 
active linkage section, the offset is relative to the beginning 
of that linkage section. 

The offset may be either a number or a symbolic name. (Note 
that all numbers are treated as octal except in a few cases 
specified later.) If a symbolic name is specified, a symbol 
table must exist for the working segment. See the pi 1 command in 
the MPM for a description of symbol table creation. If a 
symbolic name begins with a numeric character, the escape 
characters &n (for name) must precede the name, to avoid 
interpreting the name as a number. For example, 

/test/&nlO&t 

might be used to specify the location associated with FORTRAN 
line number (i.e., label) 10 i n a debug request. 

The relative offset field allows the user to relocate the 
working pointer by a constant value or register. For example, if 
the user wished to reference the fourth word after the stack 
variable he could use 

/test/i&s+U 

as the generalized address. The relative offset can also assume 

the value of a register. For example, if the a-register 

contained the value k at the time of a break, then 

/test/i&s$a 

would result in exactly the same output as above. Note the lack 
of a + sign when a register is used. (See Regi sters below.) 

The three most common values for the segment ID field are 
&t, &s, and &1. These designate that the working pointer is to 
refer to, respectively, the working segment itself, its active 
stack frame, or its active linkage section. In addition, two 
other possible values of segment ID allow alternate methods of 
referring to locations in either the working segment or its stack 
frame. 

A segment ID of &a refers to the ASCII source program for 
the working segment. Associated with this segment ID is a 
decimal line number which must immediately follow the &a. This 
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line number is used to generate a working pointer to the first 
word of code compiled for that line. A relative offset may 
follow the line number. Note that the line-number/code-location 
association can only be determined if a symbol table exists for 
the working segment. 

An example: 

/test_seg/&a219+36 

would generate a working pointer which points at the thirty-sixth 
(octal) word in the text after the first word of code generated 
for line 219 in the source for the segment test_seg. If an 
offset field is given before &a, the offset is ignored. The 
offset of the working pointer is generated solely from the line 
number and the relative offset. 

A segment ID of &p refers to the parameters of an active 
invocation of a procedure. If the current defaults specify an 
active stack frame/ a number following the &p specifies the 
parameter which is to be addressed. The offset field is ignored, 
but a relative offset may be specified. 

An example: 

/test_seg/&s;&p^+36 / alk 

will cause the stack frame for test__seg to be the working 
segment, and the first lk characters of the data contained at a 
location 36 words after the beginning of the fourth parameter 
will be printed in ASCII format. 

It is not necessary to specify all four fields of a 
generalized address. In fact/ every field is optional. If a 
field is not specified/ a default value is assumed which is 
frequently the last value that the field had. For example/ 

/test_seg/l i ne&s + 3 

followed by the generalized address 
+*» 

would be acceptable. The latter request would have been 
equivalent to 

/test_seg/l ine&s + 7 

One time that the defaults assumed are not the values of the 
previous data request is when a symbolic variable name or label 
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is specified which would cause some field to change. If this is 
the case, debug may realize that the segment I D, for example/ of 
the previous data request is not valid and set it appropriately. 
For example/ 

/test_seg/760&s 

followed by 

regp 

would cause the defaults to be changed to: 
/test_seg/140&l 

if regp is found at a relative offset of IkO (octal) in the 
linkage section. Note that the segment ID was changed to &1 
where it will remain until explicitly or implicitly changed 
again. 

Defaults are also reset to values different from the 
previous values when the segment name field is specified in a 
generalized address. In this case, the following actions are 
taken: 

1) If the segment name begins with &n/ take the rest of the 
characters composing the segment name and go to step 3 below, 
looking up the string as a name. This convention allows the 
use of debug on segments whose names are composed of numeric 
characters . 

2) If the segment name is really a segment number/ this number 
is used in a search of all active stack frames to see if one 
exists for this segment. The search is from the highest 
stack depth (deepest in recursion) to the base of the stack 
so that if an active stack frame is found/ it is the one most 
recently used. If an active stack frame is found/ the 
generalized address defaults are set as follows: 

a) working segment the one specified by the given 

segment number; 

b) offset zero; 

c) segment ID &S/ i.e./ the working pointer 

points into the latest stack 
frame for the working segment; 
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d) relative offset zero. 

If no active stack frame is found / the defaults are set as 
above except that the segment ID is &t instead of &s, i.e./ 
the working pointer points into the working segment itself. 

3) If the segment name is a reference name known in this ring, 
the segment number for the segment being referenced is found/ 
and then the defaults are calculated as if this segment 
number were given directly. 

k) If the segment name is a path name, the specified segment is 
initiated (it may already have been known) and the returned 
segment number is used as above. 

The entire set of defaults which apply to a debug data 
request can be determined at any time by issuing the control 
request to print defaults. For the format and use of this 
request, see the description under Control Requests . 

Operator Field of Data Requests 

After decoding the generalized address and coming up with 
the working pointer/ debug checks the operator. The following 
five operators are recognized: 



1) / print; 

2) ■ assign; 

3) < set a break; 

k) > alter program control (i.e./ "go to"); 

5) := call a procedure. 



if a debug request is terminated before an operator is 
encountered either by a semicolon or a "new line" character the 
default operator used is ",", i.e./ print. The one exception is 
that a blank line is ignored. The first/ second, and fifth 
operators above have operands. 

Data Requests to Look at Data 

For the print request/ there are two operands (both 
optional). The first operand is a single character specifying 
the output mode desired. (See Appendix 1 for a list of 
acceptable output modes. The default is half carriage octal.) 
The second operand is a number indicating how much output is 
being requested. For example, 
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/test_seg/U2&t,il2 



requests that 12 (octal) words starting at lk2 (octal) in the 
text of test_seg be printed in instruction format. 

The following output modes are available for data requests 
(see Appendix 1 for a full description): 



1 \ 


r\ 
\J 


occa l 


i ) 


n 


mm 1 £ d% mm mm J *s mm m*. mm, mm, 1 

naii carriage octal 


3) 


d 


decimal 


k) 


a 


ASCI 1 


5 } 


i 


i ns truct i on 


6) 


P 


poi nter 


7) 


s 


source statement 


8) 


1 


code for line number 


9) 


n 


no output (just change defaults) 


10) 


e 


floating point with exponent 


11) 


f 


floating point 


12) 


b 


bit string 


13) 


g 


graphi c 




The 


request 




+ 36, 


al6 



requests that 16 (octal) characters starting at 36 (octal) words 
after the current working pointer be printed in ASCII format. 
The output might be 

U16 1416 ">user_dir_dir>" 

The two numbers printed in most output modes should be 
interpreted as follows: 

1) If the data is from a stack frame, the first number is the 
relative offset from the base of the stack segment and the 
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second number is the relative offset within the stack frame. 
Note that if the second number is negative/ the variable does 
not exist in the current stack frame and is a parameter or a 
global variable. 

2) If the data is from a linkage section/ the first number is 
the offset within the combined linkage segment and the second 
number is the offset within the linkage section. 

3) For all other segments/ both numbers are the same and 
represent the offset within the segment. 

If a mode is not specified for output/ the last specified 
mode is used unless debug realizes another mode is more 
appropriate (e.g./ when a symbol specifies a variable of a 
different type). If the amount of output is not specified/ it is 
assumed to be one, i.e./ one word for octal output/ one line for 
source output/ one character for ASCII output/ etc. 

Data Requests to Modi f v Data 

When modifying data or code, the operands (at least one is 
expected) specify the new values to use. For example/ 

i = 7; p(l) = 206110/ 206 1 32 

would assign the octal value 7 to i and the values 206110 and 
206|32 to p(l) and p(2)/ respectively. (It is assumed that both 
are variables which are defined for the current working segment.) 
If more than one operand is specified in an assignment request/ 
consecutive words starting at the working pointer are changed. 
This is illustrated by the assignment to the pointer array p. 

There are nine acceptable forms for assignment operands: 

1) an octal number; 

2) a decimal number (a number preceded by &d); 

3) character strings; 

k) register values (see Regj sters below); 

5) instruction format input; 

6) floating point; 

7) pointers; 
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8) bit strings; 

9) variables. 

Note that all numbers typed to debug are assumed to be octal 
unless immediately preceded by the characters &d which cause such 
a number to be interpreted as decimal. There are three 
exceptions. Subscripts/ the bit offset of a pointer, and the 
number immediately following a segment ID of &a are all assumed 
to be decimal . 

Character strings being input must be bracketed by double 
quote characters ("). Bit strings being input must be bracketed 
by double quote characters and followed by a b. Floating point 
numbers must not have exponents. 

The word offset portion of a pointer value being input may 
optionally be followed by either a decimal bit offset in 
parentheses, a ring number in square brackets, or both. If both 
a bit offset and a ring number are specified, the ring number 
must follow the bit offset, with no intervening blanks. For 
example, 

p = 206125(29); q = 252|10*»C5]; rp = 211| 200(3 ) IX] 

The format for instruction input is as follows: 

(opcode address, tag) 

The address may specify a base register or a number. For 
exampl e, 

/test/lab2 * (Ida pr6|20) (sta pr0|2,*0) (nop 0) 

Note that some value must be given for the address field. The 
zero-op-code is specified by the opcode arg. 

Input of bit strings and character strings changes only 
those bits or characters specified, i.e./ a full word might not 
be completely changed. 

Several types of input may be interspersed in the same 
assignment request. For example, 

/145/13000 = "names" &dl6 126 

When different types of input are specified in one request, the 
user should be aware that the bit offset of the temporary working 
pointer might be ignored for certain types of input. In the 
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example aoove, tne 
n s ii 



r ii ^^il 

i \ji name: 



r\ 1 r» *i A 



145! 13QQ0 and 

the ASCII for "s" was placed in the first character position of 
145 1 13001. The next assignment argument (&dl6) will fill in 
145113001 with the decimal 16 and hence overwrite the "s" of the 
previous argument. 



In order to better specify more complicated assignments/ 
repetition factor is provided. If a single number (octal/ or 
&d escaping is used/ decimal) : - : 



a 
if 

au e=>tejyiM& «^ uocu/ uctiiudu appears in parentheses in an 
assignment/ the next data item is assigned repeatedly (i.e./ the 
specified number of times)/ updating the working pointer each 
time. An example of this might be: 

string - (40)" " "alpha" 

which will result in string being modified so that the first 32 
(decimal) characters are blanks/ and the 33rd through the 37th 
would get the string "alpha". 

Data Requests to Sgt Breaks 



special modification to the code of a 
executed/ causes control to pass to debug. 

states of 
etc. When 



A breakpoint is a 
program which/ when 

The user is then free to examine and change the 
variables/ set other breaks/ continue execution/ 
setting a break/ the working pointer is used directly 
points into the stack. In that case/ the working 
temporarily forced to the text. To set a break at 
loop_here in the program parse_wordS/ one would say 

/parsejwords/ loop__here< 



unless it 
pointer is 
the label 



One could also say 

/parse_words/loop_here+23< 

to set the breakpoint 23 (octal) locations after the first word 

of code for the statement labelled loop_here in the text segment. 

One could also set a break by specifying a line number. For 
example/ 



/rand/&a26< 

would set a break at the first word of code generated for line 26 
(decimal) of the source program. 

The break number printed by debug when setting a breakpoint 
is used as the name of the break when referring to breaks. After 
a break is reset/ the break number will be reused. (Resetting a 
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break restores the code to its previous value.) 

Once a break has been set at a given location/ another break 
cannot be set there. To find which breaks are set/ the user can 
use the list breaks control request (see Control Requests below). 

A program with breakpoints in it must be run from inside 
debug. See Control Requests below for executing Multics 
commands . 

Data Requests to AUer program Control 

To alter program control by issuing an explicit transfer/ 
one might say 

/216/2176> 

debug will search the stack for an active stack frame for the 
segment 216 (octal) and set the stack pointer to this frame. It 
will then transfer to 2176 (octal) in the text associated with 
this stack frame. 

If no active stack frame is found/ debug comments on the 
fact and awaits further requests. 

Dala Requests to Cal 1 a. Procedure 

The user can cause debug to call a specified procedure and 
return values into specified locations. This is done by 
specifying := as the operator in a data request. This operator 
expects one operand which is a procedure name with its associated 
arguments. There are two slightly different ways to invoke this 
feature: first/ to invoke a procedure as a function call (with 
the n+l'st argument being the returned value); and, second, to 
explicitly call a procedure. When a procedure is invoked as a 
function reference/ the current working pointer is used as the 
last argument in the argument list and/ hence/ the procedure will 
return a value into wherever the working pointer is pointing. 
For example/ 

/test/fi := sqrt_(2.0) 

This will cause the sqrt_ function to be called with the first 
argument 2.0 and the return argument of fi. Note that debug 
converts the 2.0 into a floating point number before the call. 

If no fields are present before the := is encountered, debug 
does not specify a return argument in the call. (The := can be 
thought of as "call" in a PL/I program.) For example. 
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: ■ who 



will set up a call to who$who with no arguments. Note that 
:= rename ("f oo", "moo" ) 

and 

. . rename f oo moo 

are functionally equivalent. (See Multics command execution 
under Control Requests below.) 

The method debug uses in setting up the call is to use ten 
temporary storage areas, one for each of ten possible arguments, 
debug converts the arguments appropriately and stores the values 
in these areas. Each area starts on an even location and 
consists of eight words. These temporary storage areas can be 
looked at or altered with standard data requests. They are named 
%1, . .., 110. For example, 

i= hcs__$usage_val ues(0, 0) 
U,d 

22, d 

will print two decimal numbers, both being return values from 
hcs_$usage_val ues . The actual call that debug made had two 
arguments which were both 0. (Note the first words of the first 
two storage areas were zeroed out prior to the call.) The above 
call could also have been made as follows: 

%1 hcs_$usage__values(0) 

If this were done, the second argument would not have been zeroed 
before the cal 1 . 

Variables can also be used as arguments. For example, 

sum : - sqrt_ (n) 

No conversion would be done by debug if n were fixed and sqrt__ 
expected a floating argument. 

Note that the above mentioned temporaries can be used to do 
simple mode conversion. For example, to get the floating point 
representation of 3.7 (in octal) one could say: 
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U« 3.7; /O 

To find the ASCII value for 137 (octal) one could type: 

U = 137137137137 ; ,ak 

Note that a reference to one of these storage areas causes the 
working segment to be changed to the stack segment. 

If one of the arguments in a procedure call is the character 
%, then the temporary storage for that argument is not changed 
(e.g./ overwritten with the usual argument value). Results from 
some previous work may be passed in that argument position. For 
example/ 

%1 := sqrt_(2.0) 



Registers 

The hardware registers at the time of a fault (in particular 

a break fault) are available to the user for inspection or 

change. These registers are referenced by preceding the register 

name immediately by a dollar sign ($). The register can be 

looked at by merely typing the register name. For example/ 



prints the contents of the a-register at the time of the last 
fault. If the user would like the value in the a-register to be 
changed/ he might type 

$a = U6 

for example. Decimal input is allowed also: 
$a = &dl9 

The predefined register names used by debug are: 

1) prO pointer register 0 

2) prl pointer register 1 

3) pr2 pointer register 2 
k) pr3 pointer register 3 



$a 
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Ik 






pr U 


pointer register U 


6) 


pr5 


pointer register 5 


7) 


pr6 


pointer register 6 


8) 


pr7 


pointer register 7 


9) 


prs 


all pointer registers 


10) 


xO 


index register 0 


11) 


xl 


index register 1 


12) 


x2 


index register 2 


13) 


x3 


index register 3 


lk) 


xU 


index register h 


15) 


x5 


index register 5 


16) 


x6 


index register 6 


17) 


x7 


index register 7 


18) 


a 


a-register 


19) 


q 


q-regi ster 


20) 


aq 


the a and q register considered as a single register 


21) 


exD 


exponent register 


22) 


tr 


timer register 


23) 


ral r 


ring alarm register 


2h) 


regs 


all of 10) through 23) 


25) 


ppr 


procedure pointer register 


26) 


tpr 


temporary pointer register 


27 ) 


even 


even instruction of Store Control Unit (SCU) data 


28) 


odd 


odd instruction of SCU data 


29) 


scu 


all SCU data 
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30) all all machine conditions 

The user can change these registers at will with the 
understanding that if he continues execution after the break or 
transfers directly (via > in a data request)/ the values of the 
hardware registers will be set to those of these registers. 

The values in the registers are automatically filled in by 
debug (when it is called or faulted into) with those of the last 
fault found in the stack. The user can override these values 
with the fill registers and crawl out registers control requests. 
See Control Requests below. 

The user can also define his own registers and use them as a 
small symbolic memory. For example/ 

$stal = 600220757100; $nop = 11003 
would allow the user to later say 
/test/210&t « $stal $nop $nop 

To print out the contents of all user-defined registers/ the 
user may type 

$user 

The setting and displaying of registers follows the syntax 
of ^ata requests. However/ only the register name and a possible 
new value may appear in a register request. Registers may be 
specified in a general data request only in the relative offset 
field and as operands in assignment requests. Register names 
must be less than or equal to four characters in length. Some 
examples of the use of registers follow: 

/test/i =$q 

/test/0 = $x0 
/test/46$x0/a5 
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Control Requests 

Control requests provide the user with useful functions not 
necessarily related to any specific data. The format for a 
control request is: 

.<request name> 

Control requests and data requests may be freely mixed on a 
command line if separated by semicolons. However certain control 
requests use the entire input line and hence ignore any 
semicolons found therein. Spaces are not allowed in most control 
requests . 



a list of all control requests and the 
See Appendix 2 for a complete review of 



The following is 
functions they perform, 
all requests. 

1) Trace Stack 
. t i , j 

The stack is traced from frame _L (counting from 0 at the base of 
the stack) for ± frames. If \_ is less than 0, tracing begins at 
0; if j_ is greater than the last valid frame, then only the last 
frame is traced. If j_ is not specified, it is assumed to be 0; 
if j. is not specified, all valid stack frames after j. will be 
traced. The name printed in the stack trace is the primary 
segment name unless the segment is a PL/ I or FORTRAN program in 
which case it is the entry name invoked for the stack frame 
(i.e., the label on the entry or procedure statement). 

Examples : 

.t2,3 

.tiOO 

2) Pop or Push Stack 
The general form is: 
.+1 or . -i 

The working segment is changed by moving up or down the stack X 
frames. For example, if the working segment's active stack frame 
is at depth k in the stack, then 



.+3 
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will change the working segment to the segment whose stack frame 
is at depth 7 in the stack. The defaults for working pointer/ 
segment ID, and offset are reinitialized to sp|0, &s, and 0, 
respect i vel y. 

3) S£t Stack 

The general form is 



The working segment is set to that of the i'th stack frame 
(starting at 0). The defaults are set as in pushing or popping 
the stack. 

k) Execute Mul t i cs Command 

The general form is 

..<Multics command line> 

The rest of the input line is interpreted as a standard Mul tics 
command line and is passed to the standard command processor 
after the . ,'s and any preceding characters are blanked out. Any 
valid Multics command line may be given. Note that when setting 
breaks, the program being debugged must be called in this manner 
because debug sets up a condition handler (for break faults) 
which is active only as long as debug's stack frame is active. 

5) Pri nt Def aul ts 

The general form is 
.d or .D 

The output might look like 
3 /test_seg/U(0)&t, i 212 



3 />udd>m>foo>test_seg/Ht(0)&t, i 212 

The first number (3 above) is the stack depth in octal, unless 
there is no stack frame for the working segment, in which case 
the number is -1. The working segment appears between the 
slashes (test_seg above); if .D is used, the full path name 
occurs here. The offset appears next ( Ik above); the bit offset 
(in decimal) of the working pointer appears next; the segment ID 
(&t above) appears next; the operator appears next (, for print); 
the output mode appears next (i for instruction); finally the 



. i 



or 
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segment number of the working segment appears (212 above). To 
find the name/segment number association for a given segment/ the 
user might type 

/206/,n;.d 
y i el d i ng 

60 /test_cal ler/0(0)&S/O 206 
If he knew the name, he could obtain the same output by typing 

/test_cal ler/,n; .d 

6) Conti nue Execution After £ Break 
The general form is 

• C/l 

or 

.ct/i 

or 

. col 

If j_ is not specified^ it is assumed to be 0. If \_ is specified/ 
the next j_ break faults for the current break will be skipped. 
Note that the first instruction executed upon continuation is the 
instruction on which the break occurred. If a t follows the c, 
debug will continue in temporary break mode (see below). If an r 

follows the C/ debug will reset the mode to normal (not 
temporary). 

Exampl es : 

.c continue execution 

. C/ 3 continue execution/ but skip the next three break 
faults for the current break 

.ct continue execution in temporary break mode 

7) Quit 

The general form is 

.q 

This request returns from debug to its caller. Note that if 
debug was entered via a break, then typing .q will return to the 
last procedure which explicitly called debug. 
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8) Change Output Mode 

Requests pertaining to debug's console output begin with 



a) Enter brief output mode 
.mb 

This request places debug in brief output mode, which is 
somewhat less verbose than its normal output mode. In 
particular, assignment requests and the resetting of breaks 
are not acknowledged on the user's console; the column 
headings are not printed for a stack trace; the printing of 
register contents is somewhat more compact; some error 
messages are abbreviated. 



b) Enter long output mode 



.ml 



This returns debug to long output mode, which results in 
fuller and more explicit console output. Long mode is the 
initial default. 



9) Break Requests 

The following control requests are specific to breaks and 
are recognized by having a b immediately following the 
Reference is made to the default object segment/ which is merely 
that segment which debug is currently working with when 
performing break requests. The default object segment is 
generally specified implicitly when a break is set or hit. It 
can be changed and determined on request. The default object 
segment used for break requests is not necessarily the same as 
the segment addressed by the working pointer used in data 
requests . 



Breaks are numbered (named) sequentially starting at 1 but 
the numbers are unique only for the object segment in which the 
break resides. A user may have several breaks with the same 
number defined in different object segments . 

There are two types of global requests which can be 
performed on breaks. The first, or subglobal requests, refer to 
all breaks within the default object segment. The second, or 
global requests, refer to all breaks set by the user (as 
determined from the break segment in the initial working 
directory). The subglobal request is specified by omitting the 
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break number in a break request. The global request Is specified 
by a g immediately after the b of all break requests (see below). 

The general form of all break requests is 

. bgxn. args 

where the g, the number n, and the arguments are optional. The x 
is replaced by the control character for the break request 
desired. The following break requests are currently defined: 

a) Reset a break (or breaks). The forms of the requests 
are: 

.bri to reset break 1 of the default object segment; 

,br to reset all breaks of the default object 
segment; 

.bgr to reset all breaks known to debug. 

b) List (print information about) a break. The forms of 
the request are: . 

.bli to list break 1 of the default object segment; 

,bl to list all breaks of the default object 
segment; 

.bgl to list all breaks known to debug. 

c) Execute a debug command line at break time. The 
forms for this request are: 

. bel <rest of 1 i ne> 

. be <rest of 1 i ne> 

. bge <rest of 1 i ne> 

Specifying the above request will cause <rest of line> 
to be interpreted as a debug input line whenever the 
appropriate break(s) is (are) encountered. If 
<rest of line> is null/ the specified breaks 

will have this execute feature reset to normal. 

d) Disable a break (or breaks). The forms of this request 
are: 



(c) Copyright, 1973, Massachusetts Institute of Technology 

and Honeywell Information Systems Inc. 



MULT ICS PROGRAMMERS 1 MANUAL 




Page 21 
3/26/73 



.boi. disable (turn off) break j_ of the default 
break segment; 

.bo disable all breaks in the default break 
segment; 

.bgo disable all breaks known to debug. 

Disabling a break has the effect of preventing the break 
from being taken without discarding the information 
associated with it. A user might disable a break if he 
wishes not to use it for the moment but thinks he might 
want to restore it later. A disabled break can be 
eliminated altogether by the .br request/ or re-enabled 
by the .bn request. If the break was already disabled, 
the request has no effect. 

e) Enable a break or breaks. The forms of this request 
are: 

. bnj_ enable (turn on) break j_ of the default break 
segment; 

.bn enable all breaks in the default break 
segment; 

•bgn enable all breaks. 

This request restores a previously disabled break. If 
the break was not disabled, the request has no effect. 

f) Establish a temporary command line to be executed 
whenever breaks are hit. This request is of the 
form: 

. bgt <rest of 1 i ne> 

This will cause <rest of line> to be executed as a debug 
request whenever any break is hit during the current 
process. The difference between this request and .bge 
is that when .bge is typed, the associated line remains 
associated with all breaks until they are reset, or 
until they are changed by .be requests. It is possible 
to have a temporary global command without removing 
command lines associated with individual breaks. If 
<rest of line> is null, a previously-established 
temporary command line is disestablished. 
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g) R^esk conditionally* The following requests allow the 
user to change a break into a conditional break, i.e., a 
break that will only stop if a certain condition is met. 

.bci argl -rel- arg2 

.be argl -rel- arg2 

argl and arg2 may be constants or variables, -rel- may 
be = or Whenever a specified break is encountered, 

a test is made to see if the equality exists and breaks 
according to whether the user specified ■ or "*= in 
setting up the conditional break. For example, 

.bc3 i 0 

will cause break 3 to fault whenever it is encountered 
and the value of i is nonzero. Also, 

.bc3 i « j 

will cause break 3 to fault whenever it is encountered 
and the value of i i s the same as the value of j. Note 
that the comparison is a bit by bit comparison with the 
number of bits to compare being determined by the size 
and type of the second argument. 

If no arguments are given to a set conditional request, 
the specified break is set back to a normal break. For 
exampl e, 

. be 

would cause all breaks of the default object segment to 
fault normally. 

h) Specify the number of times a break should be ignored 
(skipped). The general form is 

• bsi n 

This causes the number of skips to be assigned to break 
i of the default object segment to be r\. 

i) Print or change the default object segment. The form 
for this request is 

. bd name 
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where name is the (relative) path name or segment number 
of the segment to become the default object segment. 
If name is not specified the path name of the 
default object segment is printed. 

j) List the current segments which have breaks. The form 
for this request is: 

.bp 

This request merely interprets the break segment in the 
initial working directory. 

10) Pri nt Arguments 

The general form is 

. ai/fn 

Argument 1 for the current stack frame will be printed in the 
mode specified by m. If JL is not specified, all arguments are 
printed. If m is not specified, debug will decide the output 
mode. Valid values for m are: 



a) 


0 


f ul 1 word octal ; 


b) 


P 


poi nter ; 


c) 


d 


decimal ; 


d) 


a 


ASCI I ; 


e) 


b 


bi t str i ng; 


f ) 


1 


location of argument; 


g) 


e,f 


floating point; 


h) 


? 


debug will decide (the default value for m) . 



Ex amp 1 es : 
,a3 

ARG 3: »'>user_dir_dir M 

. 83,0 

ARG 3: 076165163145 
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Get Paul t Regi sters 



The general form is: 



.f 



For register requests debug uses the machine registers of the 
last fault found in the stack starting at the frame currently 
being looked at. (This is the default when debug is entered as a 
result of a break fault.) 

12 ) Crawl -ML Registers 

The general form is: 



For register requests debug uses the fault data associated with 
the last crawl-out (abnormal exit from an inner ring). 

Program 1 nterrupt Feature 

The user may interrupt debug by hitting the quit button at 
any time, in particular during unwanted output. To return to 
debug request level (i.e./ to where debug waits for a new 
request)/ the user should type: 



which is the standard program interrupt manager. (See the 
program_i nterrupt write-up in the MPM.) 

Temporary Break Mode, 

When debug is in temporary break mode (placed there via a 
.ct control request)/ the following actions are taken 
automati cal ly : 

1) When the user continues any break/ another (temporary) break 
is set at the first word of code for the next line of source 
code after the source statement containing the break being 
continued. If debug cannot determine the location of the 
next line of source code, the temporary break is set at the 
word of object code immediately following the break being 
cont i nued. 

2) A temporary break is restored automatically whenever it is 
continued, and only then, i.e, a temporary break/ if not 
continued/ must be explicitly reset by the user. 



.C 
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Since temporary breaks are set sequentially in a program 
(i.e./ at the next statement in the source program), any 
transfers within a program may either skip a temporary break or 
cause code to be executed which was stopped earlier with a 
temporary break. Temporary break mode is designed to be used in 
programs which are fairly uniform and sequential in their flow of 
control. Note that a user should generally list his breaks after 
using temporary break mode to see if any breaks remain active. 

f ndi rect ion 

It is quite often desirable to reference the data pointed to 
by the pointer pointed to by the working pointer, i.e., to go 
indirect through the pointer. The user can instruct debug to do 
this by typing * instead of the segment name, offset, and segment 
ID in a generalized address. For example, 

/test/regp 

might print 

1260 110 21412360 

To find what is at 21^1 2360, the user need type only (assuming he 
wanted two octal words) 

*,o2 

This causes the working pointer to be set to 21k | 2360 and, hence, 
not necessarily into the same segment as before the request. 

Implementation of Breakpoi nts 

Breakpoints are implemented by using a special instruction 
(mme2) which causes a hardware fault whenever it is executed, 
debug sets itself up as the handler for this fault and, whenever 
a break word is executed, debug gains control. When debug is 
entered via a break, it does the following: 

1) fills the registers with those of the break fault; 

2) prints the location of the break fault; 

3) waits for requests. 

When continuing after a break fault, debug changes the 
control unit information so that when it is restarted, it will 
execute the instruction which used to exist where the break word 
was placed. 
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requests made are relative to the default object segment. For 

example, any reference to break 3 really means break 3 of the 

default object segment. To change (or find out) the value of the 
default object segment, the . bd request should be used. 

Var i abl e Names for PL/ 1 Programs 

If a symbol table were created for a PL/I program using the 
table option, then names of labels, scalars, structures, and 
arrays may be used. The only restrictions are that 1) the 
entire structure name must be specified; 2) the only expressions 
which are allowed for subscripts are of the form 

variable +. constant 

where variable may be an arbitrary reference as above; and 3) 
all subscripts must appear last. If a variable is based on a 
particular pointer, that pointer need not be specified. Some 
examples of valid variable references are 

p-> a.b.c(j,3) 

a. b 

p(3,i+2) -> qp.a.b(x(xU) + l))->j.a 
Bi t Addressing 

When a working pointer is generated to a data item which is 
based or part of a substructure, a bit offset may be required. 
This bit offset is indeed kept and used. When making references 

to data relative to a working pointer with a bit offset, the 
relocated addresses may still contain a bit offset. For example, 
if the working pointer has the value 

15113706(13) 

then the request 

+16,b3 

will set the working pointer to 

1511372^(13) 
and print the three bits at this location. 
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1) 



Appendix 1 
Output Modes 

The following output modes are acceptable to debug: 
o octal 



2) h 



3) d 



5) 



6) 



7) 



The data pointed to by the working pointer is printed in 
full word octal format/ eight words per line. 

hal f carr i age octal 

The data is printed as in o format except only four 
words per line are printed. 

decimal 

The data is printed in decimal format/ eight words per 
1 ine. 

ASCI 1 

The data is interpreted as ASCII and printed as such. 
No more than 256 characters will be printed in response 
to a single request. 

i nstruction 

The $ata is printed in instruction format much as an 
assembler might do. 

poi nter 

The data is printed in pointer format/ i.e./ segment 
number and offset (and bit offset if it is nonzero). 

source statement 

One or more source statement lines are printed starting 
with the line of source code which generated the code 
pointed to by the working pointer (assumed to be 
pointing into the text). For example/ 

/test/loop_here+32,s2 

will print two lines of source code starting with the 
line which generated the code 32 (octal) words after the 
1 abel loop_here. 
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Another example: 

/test/&a219 / s 

will print line number 219 (decimal) of test.lang where 
lang is the appropriate language suffix. Note that if 
there was no code generated for the specified line/ 
debug comments on the fact/ increments the line number/ 
and tries again (forever). 

8) 1 code for line number 

The code associated with the specified line number is 
printed. The line number is determined as in s type 
output. For example, 

/test/&a27 / 1 

will print the code generated for line 27 (decimal) of 
test.lang. Note that any number following the 1 will be 
i gnored. 



9) n no output 

No output. This is used to suppress output when 
changing defaults. 

10) e floating point with exponent 

11) f floating point 

12) b bit string 

The data is printed as if it were a bit string. No more 
than 72 bit positions will be printed in response to a 
single request. 

13) g graphic 

The specified number of characters are interpreted as 
graphic characters (this is assumed to start in 
typewr i ter mode) . 
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1) Data Requests 
/s es na me/ offset 



Appendix 2 
Data and Control Requests 

see 1 D rel offset operator operands 



path name 
ref name 

seg number 
&n seg name 



number 
symbol 



&t 
&s 

&1 
&an 

&pn 



number 
regi ster 



operands 
i nput 1 i st 
function 1 i st 



gggment ID Qperators Registers Qutput Modes 



&t text 




pri nt 


$a 


0 


octal 








$q 


h 


half carriage octal 


&s stack 




ass i gn 


$aq 


d 


decimal 








$x0 


a 


ASCI 1 


&1 linkage 


< 


set break 


• 


i 


i nstruct i on 










P 


po i nter 


&an source 1 i ne 


> 


transfer 


$x7 


s 


source statement 








$prO 


1 


code for line number 


&pn parameter 


• 
• 


= call 


• 


n 


no output 










e 


floating point 








$pr7 


f 


floating point 








$exp 


b 


bi t str i ng 








$tr 


g 


graphi c 



$ral r 

$ppr 

$tpr 

$even 

$odd 

$prs 

$regs 

$scu 

$a1 1 
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2) Control Requests 



.ti/1 trace stack from frame 1 for j. frames 

. +j_ or . -J_ pop or push stack by \_ frames 

.1 set stack to j_ f th frame 

Multics command 
.d or .D print default values 

.c,j_ continue after break (ignore next 1 break 

f aul ts) 

.ct/i continue/ in temporary break mode 

.cr / j_ continue, in normal mode 

.q return from debug to caller 

.brj_ reset break j_ 

.br reset the breaks of the default object 

segment 

.bgr reset all breaks 

.bll 1 i st break 1 

.bl list the breaks of the default object 

segment 

.bgl 1 ist al 1 breaks 

.bel <line> execution line for break \_ 

.be <line> execution line for all breaks of the 

default object segment 
.bge <line> execution line for all breaks 

,boj_ disable break j_ 

.boj. disable break j_ 

.bo disable the break of the default object segment 

.bgo disable all breaks 

.bnj_ enable break j_ 

.bn enable the breaks of the default object segment 

.bgn enable all breaks 

.bgt <line> establish a temporary global command 

.bcl al -rel- a2 make conditional break j_ 

.be al -rel- a2 make conditional all breaks of 

default object segment 
• bsi n set skips of break j_ to jn 

. bd name/no. set (or print) default object segment 

.bp print all segments with breaks 

. aj_,m print argument j_ in mode m 

(modes: o, p, d, a, b, 1, e, f, ?) 
.f use registers from last fault 

.C use crawl-out registers 

.mb change to brief output mode 

.ml change to long output mode 
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Name : decam, dcm 

The decam (desk calculator with memory) command performs the 
functions of a ten-key desk calculator. In addition, it has a 
small memory and variable radix input/output. 

usase 

decam 

initiates the calculator; when ready to accept the first request 
decam types "Go". No further responses will be typed by decam 
unless it is asked to print a result or an illegal request is 
given. Successive requests are separated by new-line characters. 
All blanks are ignored. One result register is maintained, 
called A here. The following requests modify the contents of A 
as shown (n is any integer): 



typed request 

=n 
+n 
-n 
*n 
/n 
%n 
P 



computation performed 



A 
A 
A 
A 

n 



-> 
-> 
-> 
-> 
-> 
-> 



A 
A 
A 
A 
A 
A 



initial ize 
add n to A 
subtract 
mu 1 1 i p 1 y 
divide A 
divide n 



A with n 



n from A 
A by n 
by n 
by A 



print contents of A 



One additional request 
q 

will return the user to command level. 

Storage cejj_s_ 

Eight storage cells, named s, t, u, v, w, x, y, and z, may 
also be used as operands in the above requests by replacing the 
integer n with the name of a storage cell. A value may be stored 
in a storage cell by 

x s n 



where storage cell x 
the eight storage 
value of A 
used for 
(decimal ) . 
inclusive. 



receives the value of n. Of course any of 
cell names may be usedo if n is omitted the 
is used. Storage cell s contains the radix which is 
input/output conversion. It initially contains ten 
The contents of s must be in the range from 2 to 20 
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To print storage cell x, type 
P x 

Note 

All computations are done with 35-bit integers/ giving about 
10 digit precision when the radix is ten. 

Example 

The following example sums two set of numbers, then divides 
the first sum by the second. The right hand column describes the 
activity in the left hand column. 



decam user invokes decam 

Go response from decam 

= 0 user ini tal izes A 

+ 214 user adds first set of numbers 

+ 27 

+ 818 

p user requests result to be printed 

1059 decam prints the result 

decam prints a blank line 

x= user saves result in cell x 

=0 user resets A to zero for second addition 

+14 user adds second set of numbers 
+ 23 
+ 79 

p user requests result to be printed 

116 decam prints the result 

decam prints a blank line 

%x user divides A into x 

p user requests result to be printed 

9 decam prints the result 

decam prints a blank line 

q user returns to command level 



Note that if the second set of numbers had been summed first, the 
divide request would have been /x (divide A by x) instead of |x 
(divide A into x). 
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Syntax 

Only a subset of the allowed syntax of the desk calculator 
has been described above. The full syntax description is given 
as f ol lows : 

<name> ::= si t|u| v|w|x|y|z| <null field> 

<integer> (usual definition — the letters a through j 

are used as digits as necessary/ for 
radix > 10.) 

<operand> ::= <name> | <integer> 

<operator> ::= + 1 - 1 *l / 1 II Pi q 1 - 

<request> ::= <name> <operator> <operand> 
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Standard Service System 



Name : delete/ dl 

The delete command causes the 
mul t i -segment files to be deleted, 
deleting directories) and deleteforce 
segments without being interrogated). 



specified segments and 
See also delete_dir (for 
(for deleting protected 



Usage 

delete pathl. ... pathn 
1) path! is the name of the segment to be deleted. 

Note? 

The user must have write access for both the segment and its 
directory. If only the segment's write access is lacking, he 
will be interrogated as to whether he wishes to delete the 
segment. See also the MPM section for deleteforce. 



If pathj. is a link, delete will print a message, 
delete either the segment in question or the link, 
section for unlink. If path], is a directory, delete 
message; it will not delete the directory. See the 
for deletedir. 



i t wi 1 1 not 
See the MPM 
will print a 
MPM section 



The star convention may be used. 
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Standard Service System 
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Name : delete__dir, dd 

The delete_ dir command causes the specified directories (and 
any segments they contain) to be deleted. Subdirectories and 
their segments and subdirectories will also be deleted. See the 
MPM sections for delete (for deleting segments) and deleteforce 
(for deleting protected segments). 

Usage 

delete_dir path! ... pathn 
1) path! is the name of the directory to be deleted. 

Notes 

The user must have write access for both the directory and 
its superior directory. The star convention may be used. Before 
deleting each specified directory / delete_dir will ask the user 
if he wants to delete that directory* it will be deleted only if 
the user types "yes". 

Warning: protected segments in pathl or any of its 
subdirectories will be deleted. 
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Command 
3/30/73 



Name : del ete_i acl_di r, did 



This command deletes entries from a directory Initial Access 
Control List (Initial ACL) in a specified directory. A directory 
Initial ACL contains the ACL entries to be placed on directories 
added to the directory. For a discussion of Initial ACLs, see 
the MPM Reference Guide section/ Access Control. 



Usage 



delete_i acl__di r pathname acnamei ... acnamen -control_arg- 

1) pathname specifies the directory in which the directory 
Initial ACL should be changed. If it is "-wd" or 
"-working_di rectory" or omitted then the working 
directory is assumed. If it is omitted then only 
the "-a" option for acnamei is allowed. If no 
arguments are given then the entry for the user's 
name and project is deleted from the Initial ACL 
of the working directory. The star convention may 
be used. 



2) acnamei is an access control name. If no acnamei is 

specified then the user's name and project are 
assumed. acnamei. must be of the form 
person. project . tag. If one or more of the 
components is missing, then all entries in the 
Initial ACL that match the given components are 
deleted. Components missing on the left must be 
delimited by periods; however, the periods may be 
omitted on the right. 

3) control_arg may be -ring (-rg). If may appear anywhere on the 

line and affects the whole line. If it is present 
it must be followed by a digit, where user's ring 
<. digit <. 7, which specifies which ring's Initial 
ACL for directories should be affected. If this 
option is not given then the user's ring is 
assumed. 
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Examples 

delete_i acl_di r news .Faculty ..a 

will delete from the directory Initial ACL of the news directory 
all entries with project name Faculty and all entries with 
instance tag a. 

did -a 

will delete all entries from the directory Initial ACL of the 
working directory. 

did store Jones -rg 5 

will delete from the directory Initial ACL in ring 5 in the 
directory store/ all entries beginning with person name Jones. 
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Command 
3/30/73 



Name : del ete_J acl_seg / dis 

This command deletes entries from a segment Initial Access 
Control List (Initial ACL) in a specified directory. A segment 
Initial ACL contains the ACL entries to be placed on segments 
added to the directory. For a discussion of Initial ACLS/ see 
the MPM Reference Guide section/ Access Control. 

iiSflge. 

delete_i acl__seg pathname acnamel ... acnamen. -control_arg- 

1) pathname specifies the directory in which the segment 

Initial ACL should be changed. If it is "-wd" or 
"-worki ng_di rectory" or omitted then the working 
directory is assumed. If it is omitted then only 
the "-a" option for acnamei is allowed. If no 
arguments are given then the ACL entry for the 
user f s name and project is deleted from the 
Initial ACL of the working directory. The star 
convention may be used. 

2) acnamej. is an access control name. If no acnamej. is 

specified then the user 1 name and project are 
assumed. acnamei must be of the form 
person. project. tag. If one or more of the 
components is missing/ then all entries in the 
Initial ACL that match the given components will 
be deleted. Components missing on the left must 
be delimited by periods; however/ the periods may 
be omitted on the right. 

3) control_arg may be -ring (-rg). It may appear anywhere on the 

line and affects the whole line. If it is present 
it must be followed by a digit/ where user's ring 
<. digit <. 7/ which specifies which ring's Initial 
ACL for segments should be affected. If this 
control argument is not given then the user's ring 
is assumed. 
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Examples 

delete__i acl_seg news .Multics ..a 

will delete from the segment Initial ACL of the news directory 
all entries with project name Multics and all entries with tag a. 

di s -a 

will delete all entries from the segment Initial ACL in the 
working directory. 

dis store Jones -rg 5 

will delete from the segment Initial ACL for ring 5 in the 
directory store all entries beginning with a person name Jones. 



© 
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Command 
3/1/73 



Name : deleteacl, da 

This command deletes entries on an Access Control List (ACL) 
of either a segment or a directory. 

Usage 

deleteacl pathname acnamei ... acname.2 

1) pathname specifies the ACL of the segment or directory 

which should be changed. If it is "-wd" or 
"-worki ng_di rectory" or omitted/ then the working 
directory is assumed. If it is omitted/ then only 
the "-a" option for acnamei is allowed. If no 
arguments are given, then the ACL entry for the 
user's name and project is deleted from the ACL of 
the working directory. The star convention may be 
used. 

2) acnamei is an access control name. If no acnamei is 

specified/ then the user's name and project are 
assumed. acnamei must be of the form 
person. proj ect . tag. If one or more of the 
components is missing, then all entries in the ACL 
that match the given components will be deleted. 
Any components missing on the left must be 
delimited by periods; however/ the periods may be 
omitted on the right. If an acnamei would include 
*. SysDaemon. */ but does not have all three 
components specified, the ACL entry for 
♦.SysDaemon.* will not be deleted if it exists. 
If acnamei is M -a" or "-all" then the whole ACL 
will be deleted/ and the *. SysDaemon . * rw entry 
(or sma for directories) will then be added to the 
empty ACL. 

Note 

An ACL entry for *. SysDaemon. * can be deleted only by 
specifying all three components. The user should be aware that 
in deleting access to the SysDaemon project he will prevent 
Backup. SysDaemon. a from saving the segment or directory 
(including the hierarchy inferior to the directory) on tape/ 

Dumper .SysDaemon. a from reloading It, and Retr i ever . SysDaemon. a 
from retrieving it. 
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Exampl es 

deleteacl news .Faculty ..a 

will delete from the ACL of news all entries with the project 
name Faculty and all entries with the instance tag "a". 

da -a 

will delete all entries from the ACL of the working directory and 
then add an entry "* . SysDaemon . * sma". 

da test.pll *.*.* Doe 

will delete from the ACL of test.pll an entry for *.*.* and all 
entries with the person name Doe. 
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Command 

Standard Service System 

7/6/72 



N ame : deleteforce, df 

The deleteforce command causes the specified segments to be 
deleted, regardless of whether or not they are protected. 



The user must have write access for both the segment and its 
di rectory . 

If pa thj_ is a link, deleteforce will print a message; it 
will not delete either the segment in question or the link. See 
the MPM section for unlink. If pathx is a directory, deleteforce 
will print a message; it will not delete the directory. See the 
MPM section for delete_dir. 

The star convention may be used. 



Usajge. 



deleteforce pathl 



pat ha 



1) pathi 



is the name of the segment to be deleted. 



Notes 
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Command 

Standard Service System 

6/29/72 



Name : deletename, dn 

The deletename command deletes specified names from segments 
or directories which have multiple names. See the MPM sections 
for addname (for adding names to storage system entries) and 
rename (for changing names of storage system entries). 

Usage 

deletename path! ... pathn 
1) path! is the name which is to be deleted. 

Notes 

In keeping with standard practice, path! may be a relative 
path name or an absolute path name; its final portion (the 
storage system entry in question) will be deleted from the 
segment or directory it specifies, provided that doing so does 
not leave the segment or directory without a name. In the latter 
case, the user will be interrogated as to whether he wishes the 
segment or directory in question to be deleted. 

The star convention may be used. 
Example 

deletename alpha >my_dir>beta 

would delete the name alpha from the list of names for the 
appropriate segment in the current working directory, and would 
delete the name beta from the list of names for the appropriate 
segment in the directory >my__dir. Neither alpha nor beta may be 
the only name for their respective segments. 
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Command 
Development System 
8/18/71 



Name : d i spl ay_component_name, den 

The d i spl ay_component_name command converts an offset within 
a bound segment (e.g., bound__z i 1 ch_J 23017 ) into an offset within 
the referenced component object (e.g., comp|1527). It works on 
segments bound with version number h (and subsequent versions) of 
the binder. It is especially useful when it is necessary to 
convert an offset within a bound segment (as displayed by the 
default error handler or by a stack trace) into an offset 
corresponding to a compilation listing. 

It is intended to be a temporary command and will probably 
be removed when the debugging and diagnostic tools have been 
modified to perform the appropriate offset conversion themselves. 



Usage 



d ? spl ay_component_name path offset!. 



of f setn. 



1) path 



is the pathname of a bound object segment. 



2) offset! 



is an octal offset within the text of the bound 
object segment specified by "path". 



Example 



The command 



di spl ay_component_name bound_z i 1 ch_ 17523 6^251 



might respond with the following display: 



17523 
6U251 



components | 1057 
component7 | 63 
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Command 
11/13/73 



Name : do 

The purpose of the do command is to expand a command string 
given as its first argument by replacing the parameter 
designators &1 ... &9 found in it with the actual arguments 
supplied following the command string. The resultant expanded 
string is then passed to the Multics command processor for 
execution. If abbreviations are being expanded in the process, 
any abbreviations in the expanded string are first expanded. 
(See the writeup for the abbrev command.) Control arguments 
exist to print the expanded command line, to suppress its 
execution, or to pass it back as the value of an active function. 

Usage 

do ,f command__st r i ng" -argl.- ... -argn.- 

1) command__str i ng is a command line (in quotation marks). Each 

instance of the paramter designator &i_ (where 
i is a number from 1 to 9) found in 
command__str i ng is replaced by the 
corresponding actual argument argj.. If any 
argj. is not supplied, then each instance of 
&L in command_st r i ng is replaced by the null 
string. Each instance of the unique-name 
designator &! found in command_st r i ng is 
replaced by a 15-character identifier unique 
to the particular invocation of the do 
command. Finally, each instance of the pair 
&& is replaced by a ampersand. Any other 
ampersand discovered in command_st r i ng causes 
an error message to be printed and the 
expansion to be terminated. Any argument 
supplied but not mentioned in a paramter 
designator is ignored. 

2) argj_ is a character string argument to replace a 

parameter designator &1 in command_st r i ng. 

Usage &s_ a_n Active Function 

If the do command is called as an active function 

| do "commandos tr i ng" argl. ... argnl 

then, instead of executing the resultant expanded string, the do 
command passes it back as the value of the active function. 
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Modes 

The do command has three modes, the long/brief mode, the 
nogo/go mode, and the absentee/ i nteract i ve mode. These modes are 
kept in internal static storage and are thus remembered from call 
to call within a process. The modes are set by invoking the do 
command as follows: 

do mode 

where mode is one of -long, -Ig, -brief, -bf, -nogo, -go, 
-absentee, or -interactive. 

If the long/brief mode is long, then the expanded command string 
is printed on the string error_output before it is executed or 
passed back. If the long/brief mode is brief, then the string is 
not printed. The default for this mode is brief. 

If the nogo/go mode is nogo, then the expanded command 
string is not passed to the command processor for execution. If 
the nogo/go mode is go, then the expanded string is passed to the 
command processor (if the do command was invoked as a command). 
If do is invoked as an active function, then the nogo/go mode is 
ignored. The default for this mode is go. 

If the absentee/ i nteract i ve mode is absentee, then the do 
command establishes itself as a default on unit during the 
execution of the expanded command string. This is mainly of use 
in an absentee environment, in which any invocation of the 
standard default on unit terminates the process. When do is the 
default on unit, any signal caught by do merely terminates 
execution of the command string, not the process. A number of 
conditions, however, are not handled by do but are passed on for 
their standard Multics treatment; they are cput, alrm, quit, 
program_j nterrupt, command_er ror, command_query_er ror, 

command_quest i on, and record__quota__overf low. (For a description 
of these conditions see the MPM Reference Guide section, List of 
System Conditions and Default On Unit Actions.) If the 
absentee/ i nteract i ve mode is interactive, then do does not catch 
any signals. The default for this mode is interactive. 

Quote-doubl i ng ajid Reauoting 

In addition to the parameter designators &1 ... &9, the do 
command also recognizes two more sets of parameter designators. 
They are &ql ... &q9, to request quote-doubling in the actual 
argument as it is substituted into the expanded string, and &rl 
... &r9, to request that the actual argument be requoted as well 
as have its quotes doubled during subst i tutut i on. 
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Quote-doubling can be described as follows. Each parameter 
designator in the input string to be expanded is found nested a 
certain level deep in quotes. If a designator is found to be not 
within quotes, then its quote-level is zero; if it is found 
between a single pair of quotes, then its quote-level is one; and 
so on. If the parameter designator &qi is found nested to 
quote-level L, then, as argi is substituted into the expanded 
string each quote character found in argi is multiplied by 2**L 
during insertion. This permits the quote character to survive 
the quote-stripping action to which the command processor 
subsequently subjects the expanded string. If &qi is not located 
between quotes, or if argj_ contains no quotes, then the 
substitutions performed for &qi and for &i are identical. 

If the parameter designator &ri is specified, then the 
substituted argument argi is placed between an additional level 
of quotes before having its quotes doubled. More precisely, if 
the parameter designator &rj_ is found nested to quote-level L, 
then 2**L quotes are inserted into the expanded string, argi is 
substituted into the expanded string with each of its quotes 
multiplied by 2**(L+1), and then 2**L more quotes are placed 
following it. If argument argi is not supplied, then nothing is 
placed in the expanded string; this providis a way to distinguish 
between arguments that are not supplied and arguments that are 
supplied but null. If argument argi is present, then the 
expansions of &ri and of &qi written between an additional level 
of quotes are identical. 

Accessing More than Nine Arguments 

In addition to the normal parameter designators in which the 
argument to be substituted is specified by a single digit, do 
also allows the designators &(d...d), &r(d...d), and &q(d...d) 
where d...d denotes a string of decimal digits. An error message 
is printed and the expansion is terminated if any character other 
than 0 ... 9 is found between the parentheses. 



The do command is particularly useful when used in 
conjunction with the abbreviation processor, the abbrev command. 
Consider the following abbreviations: 



Examples 



AX 
FO 
P 



ADDPLI 
AUTHOR 



do "fo &l.list;ioa_ "\;pM &l;co 
do "ioa_$nnl &l;status -author $1 
do "if is &1 -then ""df &1 ,,,,M 
do "AX &l;fo &1" 
do "pll &1 -1 ist &2 &3" 



ii 



ii 
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The command 

ADDPLI alpha 

expands to 

fo al pha. 1 i st; ioa_ 1 ; p 1 i alpha;co 
The command 1 1 ne 

AUTHOR beta 
prints the author of segment beta. 
The command 1 i ne 

FO gamma 

expands to 

AX gamma; fo gamma 

which is expanded to 

if is gamma -then df gamma; fo gamma 

This shows how do can be used at several levels and how 
abbreviations can be used within abbreviations. 

The command 1 i ne 

P alpha 
generates the expansion 

pi 1 al pha -list 
while the command line 

P alpha -table 

expands to 

pll alpha -list -table 
This shows how references to unsupplied arguments get deleted. 
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Command 
8/20/73 



Name ; dprint, dp, dpi, dp2 

The dprint (daemon print) command allows specified segments 
to be queued for printing on the Multics line printer. It is 
similar to the dpunch command and the actual printing is managed 
by the same system process which manages segment punching. The 
output/ identified by the personal name contained in the 
requestor's user ID, is available from Operations. Because queue 
traffic is highly variable, no guarantee can be made as to how 
long the printing will take. 

The entry dpi places requests in the top priority queue, dp2 
places them in the second priority queue, and dp and dprint place 
them in the lowest priority queue. All requests in the first 
queue are processed before any requests in the other queues, etc. 
Higher priority queues have a higher cost associated with them. 



Usage 



dprint -ctl__argJL- 



-ct 1 _a rgn.- -pathJL- 



patha* 



1) ctl_ argi 



can be chosen from the following list 
of control arguments and can appear 
anywhere in the command line: 



-brief 
-bf 



the message "j requests signalled, k 
already queued." is suppressed. This 
control argument cannot be overruled 
later in the command line. 



copy n 
cp a 



causes a copies (n <» k) of subsequent 
segments to be printed. This control 
argument can be overruled by a 
subsequent -copy control argument. If 
the -delete control argument is 
specified for the segment, it does not 
take place until after the last copy 
has been printed. The default value 
for a is 1. 



-queue n 
-q E 



all subsequently specified segments are 
printed in priority queue a < = 3). 
This control argument can be overruled 
by a subsequent -queue control 
argument. It overrides any 

specification made through the use of 
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•delete 
•dl 



header heading 
•he heading 



destination dest 
ds dest 



the command names dpi or dp2. The 
default value tor a is 5. 

all subsequently specified segments in 
the command line are deleted after 
pr i nt i ng. 

subsequent output is identified by 
the string "heading" as well as by the 
user ID. This control argument can be 
overruled by a subsequent "-header" 
control argument. 

subsequent output is labeled with the 
the string "dest", which is used to 
determine where to deliver the output. 
(If this control argument is omitted, 
the requestor's project ID is used.) 
This control argument can be overruled 
by a subsequent -destination control 
argument. 



2) path! 



is the path name of 
queued for printing 



a segment to be 



Notes 

All control arguments can appear anywhere in the command 
line. If present, they affect only segments specified after 
their appearance. 

The -brief control argument affects only the message printed 
after the command is finished and not the processing of segments. 

The -copy control argument limits the maximum number of 
copies to k. 

The -delete control argument is the only control argument 
affecting segments that cannot be reset in a given invocation of 
the command. Once -delete appears in a line, all subsequent 
segments are deleted after printing. 

The command dp (or dpi or dp2), with no arguments specified, 
results in a message giving the status of the queue. 

The dprint command does not accept the star convention; it 
prints a warning message if a name containing asterisks is 
encountered and continues processing its other arguments. 
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Command 
8/17/73 



Name : dpunch, dpn, dpnl, dpn2 

The dpunch (daemon punch) command allows specified segments 
to be queued for punching by the Multics on-line card punch. It 
is similar to the dprint command and the actual punching is 
managed by the same system process that manages segment printing. 
Output is available from Operations, Because queue traffic is 
highly variable, no guarantee can be made as to how soon the 
punching will be performed. 

See also the MPM Reference Guide Section, Input and Output 
Fac i 1 i ties. 

The entry dpnl places requests in the top priority queue, 
dpn2 places them in the second priority queue, and dpn and dpunch 
place them in the lowest priority queue. All requests in the 
first queue are processed before any requests in the other 
queues, etc. Higher priority queues have a higher cost 
associated with them. 



Usage 



dpunch -c t 1 _a rgi - 



-ctl_arga _ -path.1- 



-pathn.- 



1) ctl_argl 



can be chosen from the following list of 
control arguments and can appear 
anyv/here in the command line: 



-brief 
-bf 



the message "j requests signalled, k 
already queued." is suppressed. This 
control argument cannot be overruled 
later in the command line. 



-copy n 
-cp n 



causes n copies ( n <= k) of all 
subsequent segments to be punched. This 
control argument can be overruled by a 
subsequent -copy control argument. If 
the -delete control argument is 
specified for the segment, it does not 
take place until after the last copy has 
been punched. The default value of n is 
1. 



-queue n 
-q n 



all subsequently specified segments are 
punched in priority queue n (n <= 3). 
This control argument can be overruled 
by a subsequent -queue control argument. 
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It overrides any 

through the use of 

dpnl and dpn2. The 
is 3 . 



specification made 
the command names 
default value for n 



•del ete 
•dl 



•header heading 
•he heading 



•destination dest 
ds dest 



-mcc 



-raw 



7punch 
7p 



all subsequently specified segments in 
the command line are deleted after 
punch i ng. 



the string "heading" 
the deck's identifying 
all subsequently spec 
the command line unless 



is added to 
information for 
fied segments in 
overruled by a 



subsequent -header control argument. 

the string "dest" is printed on the 
accompanying sheet identifying the 
output, and is used to determine where 
to deliver the deck. (If this control 
argument is omitted, the requestor's 
project ID is used.) This control 
argument can be overruled by a 
subsequent -destination control 

argument . 

the following segments in the command 
line are to be punched under character 
conversion. This control argument can 
be overruled by either the -raw or 
-7punch control arguments. 

the following segments in the command 
line are to be punched with no 
conversion. This control argument can 
be overruled by either the -mcc or 
-7punch control arguments. 

the following segments in the command 
line are to be punched under -7punch 
conversion. This is the default 
conversion mode and need only be 
specified when a number of segments are 
being requested by one invocation of 
dpunch and other modes (-mcc or -raw) 

have been specified earlier in the 
command 1 i ne. 
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2) pathl is the path name of a segment to be 

queued for punching. 

Noie_s_ 

All control arguments can appear anywhere in the command 
line. If present, they affect only segments specified after 
their appearance. 

The -brief control argument does not affect the processing 
of segments but only the message printed after the command is 
f ini shed. 

The -copy control argument limits the maximum number of 
copies to 

The -delete control argument is the only control argument 
affecting segments that cannot be reset in a given invocation of 
the command. Once -delete appears in a line, all subsequent 
segments are deleted after punching. 

The dpunch command does not accept the star convention; it 
prints a warning message if a name containing asterisks is 
encountered and continues processing its other arguments. 

The dpunch command (or dpn or dpnl or dpn2), with no 
arguments specified, results in a message giving the status of 
the specified queue. 

It is suggested that, before deleting the segment that was 
punched, the user read the deck back in and compare it with the 
original to ensure the absence of errors. 

Example 

dpunch a b -mcc -he Doe c.pll -dl -7p -he "J. Roe" a 

would cause segments a and b in the current working directory to 
be 7punched (the default conversion mode) and c.pll to be punched 
under character conversion with "for Doe" added to the heading. 
Segment a is 7punched with "for J. Roe" added to the heading and 
the segment is then deleted after punching. 
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Command 
10/9/73 



name : dump_segment , ds 



The dump_segment command prints in octal format selected 
portions of a segment. it prints out either four or eight words 
per line and can be instructed to print out an edited version of 
the ASCII representation. 



Usage 



dump_segment seg offset num -control_arg 



1 ) seg 

2) offset 

3 ) num 

k) control_arg 
-long, -lg 



is the pathname or segment number of the 
segment to be dumped. If it is a pathname, 
but looks like a number, the preceding 
argument should be -name or -nm. 

is the offset of the first word to be dumped. 
If omitted, the entire segment is dumped. 



is the number of words 
omitted, 1 is assumed. 



to be dumped. If 
list of 



can be chosen from the following 
control arguments: 



causes eight words to be printed on a line, 
Four is the default. This control argument 
cannot be used together with any of the other 
control arguments* (Its use with -bed or 
-character would result in a line longer than 
132 characers . ) 



-character, -ch causes the ASCII representation of the words 

to also appear on each line. Characters that 
cannot be printed are represented as periods, 

-bed causes the BCD representation of the words to 

also appear on each line. There are no 
non-printable BCD characters, so periods can 
be taken 1 i tera 1 1 y , 
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short/ -sh causes lines to be compacted/ to fit on a 

terminal with a short line length. Single 
spaces are placed between fields, and only 
the two low order digits of the address are 
printed, except when the high order digits 
change. This shortens BCD output lines to 
less than 80 characters. 
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Name : edm 

The edm command is the standard Multics context editor. It 
is used for creating and editing ASCI! segments. This command 
cannot be called recursively. See also the MPM Introduction 
Chapter 3, Beginner's Guide to the Use of Multics. 

Usage 

edm -pathname- 

1) pathname specifies the segment to be edited. The argument 
is optional. If pathname is not given, edm will 
begin in input mode (see Notes below), ready to 
accept whatever is typed subsequently as input; 
when the created segment is written out, its name 
may be specified as part of the write request. If 
pathname is given, but the segment does not yet 
exist, edm will also begin in input mode; 
otherwise, edm will begin in edit mode, ready to 
edit the segment specified by pathname. 

Notes 

This command operates in response to requests from the user. 
To issue a request, the user must cause edm to be in edit mode. 
This mode is entered in two ways : if the segment already exists, 
it is entered automatically when edm is invoked; if dealing with 
a new segment (and edm has been in input mode), the mode change 
characters must be issued. The mode change characters are the 
period (.) followed by a "new line" (carriage return-new line), 

issued as the only characters on a line. The command announces 
its mode by typing "Edit." or "Input." when the mode is entered. 
From edit mode, input mode is also entered via the mode change 
characters . 

The edm requests are predicated on the assumption that the 
segment consists of a series of lines to which there is a 
conceptual pointer which indicates the current line. (The "top" 
and "bottom" lines of the segment are also meaningful.) Various 
requests explicitly or implicitly cause the pointer to be moved; 
other requests manipulate the line currently pointed to. Most 
requests are indicated by a single character; for these, the 
character is generally the first letter of the name of the 
request. Only the single character is accepted by the command. 
Three requests have been considered sufficiently dangerous, or 
likely to confuse the unwary user, that their names must be 
spec i f i ed in full. 
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If the user presses the quit button while in edit mode and 
then invokes the progr am_i nter rupt command / the effect of the 
last request executed on the edited copy is nullified. (See the 
MPM write-up for progr am_i nter rupt . ) In addition any requests 
not yet executed are lost. If program_i nter rupt is typed after a 
quit in comment or input modes then all input since last leaving 
edit mode will be lost. If the user wishes to keep the input he 
must type start following the quit. 

Requests 

The requests are as follows (detailed descriptions follow 
the list / in the order of the list): 

backup 

= print current line number 

, comment mode 

mode change 



b bottom 

c change 

d delete 

E execute 

f frnd 

i insert 

k kill 

1 locate 

merge insert segment (move) 

n next 

p print 

q qu i t 

qf quitforce 

r retype 
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s substitute 

t top 

updelete delete to pointer 

upwrite write to pointer (upper portion of segment) 

v verbose 

w write 
- Request 
Format : 
Purpose: 

Spaci ng: 
Poi nter : 
Def aul t : 
Exampl e : 



- n 

f4ove pointer backwards (toward the top of the 
segment) the number of lines specified by the 
integer n. 

A space is optional between the request and the 
integer argument. 

Set to the nth line specified before the current 
1 i ne * 

If xl is null, the pointer is moved up only one 
1 i ne. 



Before : 



Request : 
After: 



a: procedure; 

x = y; 

q = r; 

s = t; 
-> end a; 

-2 

a: procedure; 

x = y; 
-> q = r; 

s = t; 

end a; 
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Format : 
Purpose : 
Po i n t e r : 
j_ Request 
Format : 
Purpose: 



Poi nter : 
b Request 
Format : 
Purpose : 

Poi nter : 
Sl Request 
Format : 
Purpose : 



Spac i ng: 
Poi nter : 



Print current line number 
Unchanged . 



The editor will print lines, starting with the 
current one, leaving off the carriage return. It 
then switches to input mode, letting you type the 
rest of the line (comment, "new line", etc.). The 
process then repeats with the next line. The mode 
change characters will return you to edit mode. 

Left pointing to the last line printed. 



Move pointer to the end of the segment and switch 
to i nput mode . 

Set after the last line in the segment. 



c n. /st r i ngl/str i ng2/ 

Replace every instance of stringl by string2 in 
the number of lines indicated to be searched by 
the integer n. edm responds to each change by 
printing the line with the changed text in red if 
the user is in verbose mode (see the v request), 
or with "edm: Substitution failed." if stringl is 
not found. 

A space before n. and between jn and the stringl 
delimiter is optional. 

Set to the last line scanned. 
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Del imi ters 



Def aul t : 



Example : 



Any character not appearing in stringl or string2 
can delimit the strings (/ is shown in the 
format). A delimiter following string2 is 
optional . 

If an integer is absent/ only stringl of the 
current line is changed. If stringl is absent/ 
string2 is inserted at the beginning of the line. 



Before : 



No t e : 

d Request 
Format : 



Request : 
Response : 

After: 



a: procedure; 
-> x = y. 

q = r. 

s = t; 

end a; 

c2/./;/ 

x = y; 
q ■ r; 

a: procedure; 

x ' - y; 
-> q = r; 

s = t; 

end a; 



For compatibility wi th qedx, this request may also 
be given as s (for substitute). 



d n 



Purpose: 



Causes n. lines to be deleted where n. is an 
integer. Deletion begins at the current line. 



Spac i ng: 
Poi nter : 



A space is optional between d and n. 

Set to "no line" following the line deleted. That 
is / an i request or a change to input mode would 
take effect before the next nondeleted line. 



Def aul t : 
Note : 



If n. is null/ only the current line is deleted. 

The requests c, d, n, and p count "no line" when 
issued immediately after a delete request. 
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L Request 
Format : 
Purpose : 

Spaci ng: 
Poi nter : 
I Request 
Format : 
Purpose : 



Spac i ng : 

Poi nter : 
Def aul t : 

L Request 
Format : 

Purpose : 
Spac i ng: 

Poi nter : 
Hef aul t : 
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F commandl i ne 

Pass commandl ine to the command processor for 
execution as a command line. 

A single space following E is not significant. 
Unchanged . 



f string 

Search segment for a line beginning with the 
string. Search starts at the line following the 
current line and continues around the entire 
segment until the string is found or until return 
to the current line. The current line is not 
searched. If the string is not found, the error 
message "edm: Seach failed." is printed. If the 
string is found and the user is in verbose mode, 
the line containing the string is printed. 

A single space following f is not significant. 
All other leading and embedded spaces are used in 
search i ng. 

Set to the line found, or remains at the current 
line if the line is not found. 

If the string is null, edm searches for the string 
requested by the last f or 1 request. 



i newl i ne 

Insert newl ine after the current line. 

The first space following i is not significant. 
All other leading and embedded spaces become part 
of the text of the new line. 

Set to the inserted line. 

if newline is null, a blank line is inserted. 
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No t e : 

k Request 
Format : 
Purpose : 

Poi nter : 
Note : 
i Request 
Format : 
Purpose : 



Spaci ng : 

Poi nter : 
Def aul t : 
Ex amp! e : 



Immediately after a t (top) request, an i request 
causes the newline to be inserted at the beginning 
of the segment. 



To inhibit (kill) responses following a c, f, 1, 
n, or s request. 

Unchanged . 

See v (verbose) request for restoring responses. 



1 string 

Search segment for a line containing the string. 
Search starts at the line following the current 
line and continues around the entire segment until 
the string is found or until return to the current 
line. The current line is not searched. if the 
string is not found, the error message "edm: 
Search failed," is printed. if the string is 
found and the user is in verbose mode, the line 
containing the string is printed. 

A single space following 1 is not significant. 
All other leading and embedded spaces are used in 
searchi ng. 

Set to the line found, or remains at the current 
line if the line is not found. 

If the string is null, edm searches for the string 
requested by the last 1 or f request. 



Before: a: procedure; 



-> 



x = y; 
q = r; 
s = t; 
end a ; 



Reques t : 



1 x = 
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merge Request 
Format : 
Purpose : 

Spac i ng: 
Po i n t e r : 
Def aul t : 

n Request 
Format : 
Purpose : 
Spac i ng : 
Po i n t e r : 

Def aul t : 
Note : 

p. Request 

Format : 
Purpose : 

Spaci ng: 
Po i nte r : 
Def aul t : 
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After: a: procedure; 

-> x = y; 
q = r; 
s = t; 
end a; 



merge path 

The segment specified by path is inserted after 
the current line. 

A single space following merge is not significant. 

Set to the last line of the inserted segment. 

If path is not given, the name given in the 
invocation of edm is used. 



n n. 

Move pointer down the segment n lines. 

A space is optional between n and the integer n.. 

Set to the nth line specified after the current 
1 i ne. 

If the integer n is null, the pointer is moved 
down only one line. 

The printed response to this request can be shut 
off using the k request. 



P n 

XL lines will be printed, beginning with the 
current 1 i ne. 

A space is optional between p and the integer n.. 
Left pointing to the last line printed. 
If n is null, the current line is printed. 
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Note : 



<1 Request 
Format : 
Purpose: 



Poi nter : 

qf Request 
Format : 
Purpose : 

jr Request 
Format : 

Purpose: 
Spaci ng: 

Po i nter : 
Def aul t : 

s_ Request 
Note : 



A print request in edm may be aborted by pressing 
the quit button and typing pi or 
program_i nter rupt . This will put edm in a state 
where it is ready to accept another request. (See 
the MPM write-up for progr am_i nter rupt . ) 



To exit edm and return to the caller, usually 
command level. If no write request has been made 
since the last change to the edited text, edm will 
warn the user that the changes wi 1 1 be lost and 
ask if he still wishes to quit. 



If the user is queried and answers 
pointer is unchanged. 



no, then the 



qf 

To exit from edm directly without being warned or 
quer i ed. 



r newl i ne 

Replace current line with newline. 

One space between r and newline is not 

significant. All other leading and embedded 
spaces become part of the text of the new line. 



Unchanged . 

I f newl i ne is nul 1 , 
current line. 



a blank line replaces the 



Used identically to the c request. 
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_t Request 
Format : 
Purpose : 
Poi nter : 

Note : 



Moves pointer to the first line of the segment. 

At "no line" immediately above the first line of 
text . 

An i (insert) request immediately following a t 
request causes insertion of a text line at the 
beginning of the segment. 



updel ete Request 
Format: updel ete 

Purpose : 



Delete all lines above (but not 
current 1 i ne. 



including) the 



Pointer: Unchanged. 
upwr i te Request 



Format : 
Purpose : 

Spaci ng: 

Poi nter : 
Hef aul t : 

No t e : 



upwrite path 

All the lines above the current line (but not 

including the current line) are saved in the 

hierarchy in the segment specified by path. 



A single space 
s i gni f i cant . 

Unchanged . 



following upwrite is not 



If path is not given, the name given in 
invocation of edm is used. 



the 



The lines written out are deleted from the edit 
buffers and thus are no longer available for 
edi t i ng. 
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v Request 
Format : 
Purpose : 

Poi nter : 
Note: 
w Request 
Format : 
Purpose : 



Spaci ng: 
Po i n t e r : 
Def aul t : 



Causes edm to print responses following a c, f, 
1, n, or s request. This is the default mode. 

Unchanged . 

See k (kill) for inhibiting verbose mode, 
w path 

To write out (save) the edited copy. path can 
stipulate the directory and the entry name within 
the directory in which the segment is to be saved. 
If only the entry name for the saved copy is 
given, the working directory is assumed. 

A space between w and path is not significant. 

Set to "no line" at the end of the segment. 

!f path is null, and if the original name of the 
segment is not null, the edited segment is saved 
under the original name; the original segment is 
deleted. If path is null and no previous segment 
exists, an error message is printed and edm looks 
for another request. 



Note: 



To terminate editing without saving 
copy, see the qf (quitforce) request. 



the edited 
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Name : endflle 

The endf Me command causes the FORTRAN I/O system to close 
one or all of the FORTRAN I/O files which are still open after 
the end of the execution activities during which the I/O files 
were referenced. If is useful when a FORTRAN program did not 
proceed to completion/ such as when it was interrupted by the 
user pressing his quit button. 

Msage 

endfile file__id 

1) f f 1 e i d is a one- or two-digit number which identifies the 

file to be closed. If file_id is "-all", then all 
of the FORTRAN I/O files still open in the process 
are closed. 



(c) Copyright, 1973, Massachusetts Institute of Technology 

and Honeywell Information Systems Inc. (END) 



MULT ICS PROGRAMMERS ' MANUAL 



en ter 



Command 
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Nam 



enter, e 
enterp, ep 



These commands are used by anonymous users to gain access to 
Mul tics, enter is actually a request to the answering service to 
create a process for the anonymous user. Therefore, these 
commands can only be used from a terminal connected to the 
answering service; that is, one which has just dialed up, or one 
which has been returned to the answering service after a 
terminated session with a "logout -hold" command. 

Anonymous users who are not to supply a password use the 
enter (e) command. Anonymous users who are to supply a password 
use the enterp (ep) command. 



Usage 



enter -anonymous_name- project -cont rol_args- 



1) anonymous_name 



2) project 



3) control_args 



-brief, -bf 



-home_dir path 
-hd path 



is an optional identifier which is not 
checked by the system, but is passed to 
the user's process overseer as if it 
were a person ID. If anonymous_name is 
not specified, it will be assumed to be 
the same as the project ID. 



is the identification 
proj ect . 

may be chosen from the 
of control arguments: 



of the user's 



f ol 1 owi ng 1 i st 



Messages associated with a successful 
login will be suppressed. If the user 
is using the standard process overseer, 
the message of the day will not be 
pr i nted . 



The user's home directory will 
to the path specified, if the 
project administrator allows 
specify his home diretory. 



be set 
user ' s 
him to 



-process_over seer path The user's process overseer will be 
-po path the procedure given by the path 

specified, if the user's project 
administrator allows him to specify his 
process overseer. 
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-no nr 



r i nt_of f -npf 



-print_off, -pf 



-no_preempt, -np 



The system will overtype several lines 
to provide a black area for the user to 
type his password. 

The system will not overtype an area 
for the password, since the user's 
terminal responds to the printer-off 
control sequence. 

If the user can only be loosed in by 
preempting some other user in his load 
control group, refuse his login 
i ns tead. 



-no_start_up, -ns 



-account id, -ac id 



If the user has a start_up.ec segment, 
and the project administrator allows 
the user to avoid it, instruct the 
standard process overseer not to 
execute it. 

Replace the normal account identifier 
for the user with id. (This control 
argument currently has no effect.) 



-force 



If the user has the 
attribute, log the 
po s s i b 1 e . 



guaranteed 
user in if 



1 ogi n 
at al 1 



Note 



See the .1PM Reference Guide section on the Protocol for 
Logging In for an explanation of the responses to the enter and 
enterp commands. 
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Name : en ter_abs_reques t, ear 

The en ter_abs_reques t command allows a user to request that 
an absentee process be created for him. An absentee process 
executes commands from a segment and places its output in another 
segment. The time before which this process is not to be created 
may be specified. 



The principal difference between an absentee process and an 
interactive one is that M user__i nput" is attached to an absentee 
control segment containing commands and control lines; 
"user_output" is attached to an absentee output segment as well. 



The absentee 
segment. (See 



control segment has the 
exec_.com in the MPM.) 



same syntax as an exec_.com 



________ 



enter_abs_reques t pname -ca__- 



-can- -ag argi 



argn 



1) pname 



specifies the path name of the 
absentee control segment associated 
with this request. The entry name 
must have the suffix .absin 
although it may be omitted in the 
command. Pname must be the first 
argument to the command. 



2) cai 



-output_.fi le pname 
-of pname 



is selected from the 
of control arguments 
in any pos i t i on: 



f o 1 1 ow i n g list 
and may appear 



indicates that the user wishes to 
specify the name of the outout 
segment. It must be followed by 
the path name of the absentee 
output segment. 



-restart, -rt 



-limit n, - 1 i n 



indicates that the computation 
specified by this request may be 
started over again from the 
beginning if interrupted (e.g., by 
a system crash). The default is 
not to restart the computation. 

indicates that the user wants to 
place a CPU limit on the time the 
absentee process will use. It must 
be followed by a positive integer 



(c) Copyright, 1972, Massachusetts institute of Technology 
All rights reserved. 



en ter__abs_reques t 



MULTICS PROHRAMM.FRS 1 MANUAL 



Page 2 



specifying the limit, in seconds. 
The default is no user supplied 
limit. There is a system enforced 
limit which an absentee process may 
use. Currently this absolute limit 
is twenty minutes. 



-queue £/ -q £ 



•time "def er red_t i me' 
tm "def erred__t ime" 



indicates in v/hich priority queue 
the request is to be placed. It 
must be fol lowed by an integer 
specifying the number of the queue. 
If this option is omitted, the 
request is placed in the third 
queue. 

indicates that the user wishes to 
delay creation of the absentee 
process until a specified time. It 
must be followed by a character 
string representing this time. The 
format of the deferred time is any 
character string acceptable to the 
convert_date_to__b f nary_ sub rout i ne, 
(See conver t_ date__to_bi nary_ in the 
MPM.) If the time consists of more 
than one component, it should be 
enclosed in quotes. 



-brief, -bf 



indicates that the message "j 
already requested." is to be 
suppressed. 



3) -arguments, -ag 



is an optional control argument 
which indicates that the absentee 
control segment requires arguments. 
If present, it must be followed by 
at least one argument. All 
arguments following -ag on the 
command line will be taken as 
arguments to the absentee control 
segment. Thus -ag, if present, 
must be the last control argument 
to the enter_abs_request command. 



h) argl 



is an argument to 
control segment. 



the absentee 
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If the path name of the output segment is not specified, the 
output of the absentee process wi 11 be directed to a segment 
whose path name is the same as the absentee control segment, 
except that it has the suffix .absout. 

The command checks for the existence of the absentee input 
segment and will reject a request for an absentee process if it 
is not present. 

The effect of specifying the -time option is as if the 
en ter_abs__reques t command was issued at the deferred time* 

Suppose that a user wants to request an off-line 
compilation. A control segment would be constructed called 
absentee__pl 1 , absi n containing: 

cwd current 

pll x -table -symbols 

dp -dl x. 1 i st 

logout 

The command line 

enter_abs_ reques t absentee_pl 1. absi n 

would cause an absentee process to be created (some time in the 
future) which would: 

1) set the working directory to a directory "current" inferior to 
the user's normal initial working directory; 

2) compile a PL/ I program named x.pll with two options; 

3) dprint one copy of the list segment; 
k) log out. 

The output of these tasks would appear in the same directory as 
absentee_pl 1 . absi n in a segment called absentee_pl 1 . absout . 

Suppose that an absentee control segment, trans. absin, 
contained the following: 
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cwd &1 

&2 S3 -list £<U 
&goto &2.a 
&label pll.a 

fo S3, list; ioa_ ""I; pi i %3; co 

&1abel aim. a 

dp -dl &3. 1 i st 

&goto &2.b 

&label pll.b 

&3 

&label alm.b 

logout 

The command 

ear trans -li 300 -rt -ag'work pi 1 x -map 

would cause a request for an absentee process to be made in queue 
3 which will set the working directory to the directory "work" 
inferior to the normal initial working directory/ then compile a 
PL/I program x.pll in that directory, produce a listing segment 
containing a map, append to the listing segment linkage 
information, issue a dprint request for the listing segment, and 
execute the program x, just compiled in the absentee process. 
There would be a CPU limit of five minutes placed on this 
process. 

The command 

ear trans -rt -tm "Monday midnight" -q 2 -ag comp aim yz 

would cause a request for an absentee process to be placed in 
queue 2 which will set the working directory to the directory 
"comp" inferior to the initial working directory, assemble an ALM 
program named yz.alm, produce a listing segment, and issue a 
dprint request for the listing segment constructed. This process 
will not be created until after midnight of the next Monday. 
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Pa 
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ge 5 
^/72 



Both absentee processes would issue a logout command as the 
last command in the process. 

Both absentee computations could he restarted from the 
beginning if interrupted for any reason. 
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Name: exec_com, ec 



The exec_com command is used to execute a series of command 
lines contained in a segment. It allows the user to construct 
command sequences that are invoked frequently without retyping 
the commands each time. In addition the segment can contain 
control statements that permit more flexibility than the simple 
execution of commands. Facilities exist for: 

1. substitution of arguments to the command for special strings 
in the exec_com segment; 

2. control of I/O streams; 

3. generating command lines, control statements and input lines 
condi t i onal 1 y ; 

h. combining several exec_.com sequences into one segment; and 

5. altering the flow of control. 

Usage 

exec_com pathname -argl- -arg2- ... -a rgn- 

1) pathname is the pathname of the segment containing the 

commands to be executed and control statements to 
be interpreted. The entry name of the segment 
must have the suffix ".ec", although the suffix 
can be omitted in the command invocation. 

2) argl is the string to be substituted for special 

strings in the .exec_.com segment. 

The I npu t Segment 



The exec_.com segment should contain only command lines, 
input lines and control statements. It is normally created using 
a text editor, such as edm or qedx. The exec_com command can be 
used. in conjunction with the abbrev command to forrr abbreviations 
for command sequences that are often used. 

When the character "&" appears in the exec_com segment, it 

is interpreted as a special character. It is used to denote a 
string used for argument substution and to signify the start of a 
control statement. 
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Argument Subst I tut Ion 

Strings of the form "&V* in the exec_com segment are 
interpreted as dummy arguments and are replaced by the 
corresponding argument to the exec__com command. For instance/ 
argl is substituted for the string and arglO is substituted 

for "&10". 

The character M &" should be followed by a number, j_, or by 
the string n ec_name n . If argl is not provided, is replaced 

by the null string. The string "&ec_name" is replaced b^ the 
entry name of the exec_com segment without the ",ec M suffix/ the 
string "&0" is replaced by the pathname argument to exec_com, 
just as it was given to the command. 

Argument substitution can take place in command lines, input 
lines or in control statements, since the replacement of 
arguments is done before the check for a control statement. 

Control Statements 

Control statements permit more variety and control in the 
execution of the command sequences. Currently there are twelve 
control statements: Slabel, &goto, ^attach, fidetach, &input_line, 
&command_J i ne, Sready, Sprint, &if, &then, and Seise. 

Control statements generally must start at the beginning of 
a line with no leading blanks. Exceptions to this rule are the 
Sthen and Seise statements, which can appear elsewhere. Also 
when a control statement is part of a THEN_CLAUSF or an 
ELS F_CLAUS E, it does not have to start at the beginning of a 
line. 

1. Slabel and Sgoto 

These statements permit the transfer of control within an 
exec_com segment. 



&label locat i on identifies the place to which a goto control 

statement transfers control. location is any 
string of 32 or fewer characters identifying 
the label. 



&goto locat i on causes control to be transferred to the place 

in the exec__com segment specified by the 
label locat i on . Execution then continues at 
the line immediately following the label. 



(c) Copyright, 1973, Massachusetts Institute of Technology 

and Honeywell Information Systems Inc. 



MULT ICS PROGRAMMERS* MANUAL 



exec com 



Page 3 
11/20/73 



2. &attach, &detach and &i nput_i I ne 

These statements allow the control of the I/O stream 
"user_i nput" . 



&attach 



Sdetach 



&i nput_l i ne on 



& i nput_l i ne off 



causes the I/O stream "user_input" to be 
attached to the exec_com segment. This means 
that if this control statement is executed, 
all input read by subsequent commands is 
taken from the segment rather from the stream 
"user_i/o M . 

causes the I/O stream "user_i nput" to be 
reverted to its original value. The default 
is detach rather than attach. 

causes input lines returned when using the 
Sattach feature to be written on the stream 
"user_output" . 

causes such input lines not to be written 
out. The default is on. 



3. &command_l i ne, &ready and &print 

These statements allow the control of the I/O stream 
"user_output" . They are useful as tools in observing the 
progress of the exec_com execution and in printing messages. 



&command_l i ne on 

&command_l i ne off 
&ready on 



causes subsequent command lines to be written 
on the stream "user_output" before they are 
executed . 

causes subsequent command lines not to be 
written out. The default is on. 

causes the invocation of the user's ready 
procedure after the execution of each command 
line. 



Sready off 



causes the user's ready procedure not to be 
invoked. The default is off. 



Sprint char_string causes the character string following Sprint 

to be written out on the I/O stream 
"user_output" . The character is treated 

as a special character in an Sprint 
statement. The following is a list of 
strings that can appear and the characters 
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that replace them: 
string replacement 



new line character 
form feed 
horizontal tab 



No other characters should appear fol lowing 
"-" in the &print statement. 

k. fcquit 

Squit causes exec_com to return to its caller and 

not to execute subsequent command lines. 

5, &if, &then and &else 

These statements provide the ability to generate command 
lines, input lines and control statements conditionally. 

The form of these control statements is: 

&if [ACTI VE_FUNCT!ON -argl- ... -argn-]] 
&then THEN_CLAUSF 
Seise ELSE_CLAUSE 

An active function in an &if control statement is evaluated. 
If the value of the active function is the string "true", 
THEN_CLAUSE is executed. If the value is "false", ELSE_CLAUSE is 
executed. 

&if [ACT I VE_FUNCT I ON -argl- ... -argn-] , 

This statement must start at the beginning of 
a line. The active function is any active 
function (user-provided or system-supplied) 
that returns as its value a varying character 
string with the value "true" or "false". The 
arguments to the active function can 
themselves be active functions. (Nesting of 
active functions is permitted.) The active 
function and its optional arguments, enclosed 
in brackets, must be on the same lire as the 
&if statement. 

&then THEN_CLAUSE This statement must immediately follow the 

&if statement; it can appear on the same 
line or on the following line. THEN_CLAUSE 
is an exec_com statement, and can include a 
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command line, an Input line, the null 
statement and most control statements. The 
exceptions are &label, &if/ &then and &else. 
(Nesting of &if statements is not permitted.) 
THEN_CLAUSE must be on the same line as the 
Sthen statement. 

&else ELSE_CLAUSE This statement is optional. When it appears 

it must immediately follow the &then 
statement; it can appear on the same line or 
on the following line. ELSE_CLAUSE is an 
exec_com statement, and can include a command 
line, an input line, the null statement and 
most control statements. The exceptions are 
Slabel, &if, &then and &else. ELSE_CLAUSE 
must be on the same line as the &else 
statement. 

The active functions described in the MPM Reference Guide 
section, Logical Active Functions, are frequently used in the &i f 
control statement. 

Notes 

If a line begins with the "&" character but is not one of 

the current control statements, the entire line is ignored. This 
is one way of including comments in the exec_com segment. The 

user is cautioned to leave a blank immediately following the "&" 

to i nsure compat i bi 1 i ty with control requests to be added to 
exec_com in the future. 

The segment executed by exec_com can contains calls to 
exec_com. The user is cautioned against frivolous use of this 
feature when using the &attach feature. When exec_com is called 
from an exec_com using this feature, the input read by commands 
in the second exec_.com is read from the first exec_com segment. 
Generally if the Sattach feature is used, all calls to exec_.com 
should be preceded by &detach control statements. 

Several exec_coms can be combined into one segment, by using 
the dummy argument "&ec_name" together with the &label and &goto 
statements. If exec_coms are grouped together, the exec_com 
segment should have all the names on its storage system entry 
that can replace "&ec_name" (concatenated with a M .ec" suffix). 
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Examples 

1. Assume that the segment a.ec in the user's working directory 
conta i ns : 

pll &1 -table -1 ist 
dprint -dl &1. 1 i st 
&qui t 

The command 

exec_com a foo 

would cause the following to be executed: 

pll foo -table -list 
dpr i nt -dl foo. 1 i st 

2. Assume that the segment b.ec in the user's working directory 
has an additional name a.ec and contains: 

&goto &ec_name 
& 

&label b 
print &1 1 99 
&qui t 
& 

&label a 

pll &1 -table -list 
dprint -dl fcl.list 
&qui t 

The command 

exec_.com b my__file 

would cause the following to be executed: 

print my_f i le 1 99 
The command 

exec_com a foo 

would cause the following to be executed: 

pi 1 foo -tab! e -list 
dpr i nt -dl foo. 1 i st 



cl Copyright/ 1973/ Massachusetts Institute of Technology 

and Honeywell Information Systems Inc. 



MULT ICS PROGRAMMERS 1 MANUAL 



exec com 



Page 7 
11/20/73 



5. Assume that the segment d.ec In the user's working directory 
contains the following: 

Sif [[exists segment Sl.pll} Sthen 

&else Sgoto not_found 

pll &1 -table -list 

dprint -dl SI. list 

&quit 

SI abel not__found 
Sprint &l.pll not found 
&qui t 

If the segment foo.pll exists, the command 

exec_com d foo 

would cause the following to be executed: 

pi 1 foo -table -1 i st 
dprint -dl foo, list 

If the segment foo.pll did not exist, the command 

exec_com d foo 
would output the following: 

foo.pll not found 

h. Assume that the segment test.ec in the user's working 
directory contains: 

Sprint begin Sec_name exec_com 

&command_l i ne off 

create SI. pll 

Scommand_l i ne on 

Sattach 

edm Sl.pl 1 

i &1: proc; 

Si nput_l i ne off 

i end &1; 

w 
q 

Sdetach 
Sgoto &2 
&1 abel compi 1 e 
pll SI 

SI abel nocompi 1 e 

Sprint end Sec_name SI S2 exec_.com 
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The command 

exec_com test x compile 

produces the following output: 

begin test exec_com 

edm x.pll 

edit 

i x: proc; 

pll x 
PL/1 

end text x compile exec__com 
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Names : file_output, fo 

con sol e_output, co 

The file__output command allows the user to direct the I/O 

output stream "user^output" to a specified segment. The 

console^ output command allows the user to direct it back to the 
termi nal . 

Usage 

f«le_output -pathname- 
consol e_output 

1) pathname is an optional segment path name. If is not 
present, the file_output command will direct 
output to the segment, output_file, in the user's 
working directory. If the specified segment does 
not exist (pathname or output_f i 1 e), it will be 
created. If it does already exist, subsequent 
output will be appended to the end of the segment. 

Note 

To avoid getting ready messages in the output file the 
file_output and console_putput commands should appear on the same 
line of console input. (See Examples below.) 

Examples 

The sequence of commands 

file_output my_info 

list -a 

list -p >sample_dir -d 
consol e_output 

will place in the segment my_info, in the user's working 
directory, a listing of all entries in his working directory and 
a listing of all directories contained in the directory 
>sample_dir. Note that the ready messages from the file_output 
command and the two invocations of the list command will also 
appear in my_info. 
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The command 1 i ne 

fo my_info; list -a; list -p >sample_dir -d; co 

has the same affect as the first example except that no ready 
messages will appear in my_info. 
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Name : fortran, ft 



The fortran command invokes the FORTRAN compiler to 
translate a segment containing the text of a FORTRAN source 
program into a Multics object segment. A listing segment is 



optionally produced, 
working directory. 



These results are placed in the user's 



Usase 



fortran pathname -cont rol_argl.- 



-control_argn- 



1) pathname 



2) cont rol_a rgj_ 



-source, -sc 



-symbols, -sb 



-map 



-assembl y 



-list, -Is 



is the path 
that is to 
compi ler . 
entry name, 



name of a FORTRAN source segment 
be translated by the FORTRAN 
A directory path name and an 
segname, are derived from path 



name by calling expand_path__. The compiler 
takes its input from segname. fort ran . 



can be chosen from 
control arguments: 



the following list of 



produces 
1 i st ing " 
1 i s t i ng . 



a 1 i ne-numbered 
of the program. 



pr i ntabl e ASC I I 
The default is no 



lists the source program as above and all 
the names declared in the program with their 
attributes. The default is no symbols. 



lists the source program and 
above followed by a -map of the 
generated by the compilation, 
control argument produces 
information to allow the user to 
problems online. The default is 



symbols as 
object code 
The map 
suf f ic ient 
debug most 
no map. 



lists the source program as for the -source 
control argument followed by an 

assembly-like listing of the compiled 
program. Note that producing an 

assembly-like listing significantly 

increases compilation time and should be 
avoided whenever possible by using the -map 
control argument. The default is no list. 

lists the source program and symbols as for 
the -symbols control argument followed by 
Note that use of the -list control argument 
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significantly increases compilation time and 
should be avoided whenever possible by using 
the -map control argument. The default is 
no list. 



-brief, -bf causes error messages written into the 

stream "er ror__ou tpu t" to contain only an 
error number, statement identification, and, 
when appropriate, the identifier or constant 
in error. In the normal, non-brief mode, an 
explanatory message of one or more sentences 
is al so wr i tten . 



-severityl, -svi 



causes error messages whose severity is less 
than 1 (where j_ is 1, 2, 3, or k; e.g., 
severity3) to not be written into the 
"error_output" stream although all errors 
are written into the listing. The default 
value for 1 is 1. 



-check, -ck 



is used for syntactic and semantic checking 
of a FORTRAN program. Only the first phase 
of the compiler is executed. Code 
generation is skipped as is the manipulation 
of the working segments used by the code 
generator . 



-optimize, -ot invokes an extra compiler phase just before 

code generation to perform certain 
optimizations such as the removal of common 
subexpressions. Use of this control 
argument adds 5-10% to the compilation time. 



table, -tb generates a full symbol table for use by 

symbolic debuggers; the symbol table is part 
of the symbol section of the object progran 
and consists of two parts: a statement 
table that gives the correspondence between 
source line numbers and object locations, 
and an identifier table containing 
information about every identifier used by 
the source program. This control argument 
usually causes the object segment to become 
significantly longer. 



-brief_table, -bftb 

generates a partial symbol table consisting 
of only satement labels for use by symbolic 
debuggers. The table appears as the symbol 
section of the object segment produced for 



(c) Copyright, 1973, Massachusetts Institute of Technology 

and Honeywell Information Systems Inc. 



MULT ICS PROGRAMMERS' MANUAL 



fort ran 



Page 3 
10/1/73 



the compilation. This control argument does 

not significantly increase the size of the 
object program. 

causes extra code to be produced for all 

subscripted array references, to check for 

subscript valu.es exceeding the declared 

bound dimems/fon . Such an error causes the 
subscr i ptrang.e condition to be signalled. 

generates additional code to meter the 
execution of individual statements. Each 
statement in the object program contains an 
additional instruction to increment an 
internal counter associated with that 
statement. After a program has been 
executed, the profile command can be used to 
print the execution counts. See the MPM 
command write-up of the profile command. 

The following two control arguments are available for users 
who wish to maintain their FORTRAN source segments in ANSI card 
format . 

-card specifies that the source segment is in card 

image format. 

-convert specifies that the source segment is in card 

image format. The compiler generates a 
segment, segname . converted, in the user's 
working directory, in Multics FORTRAN 
format. All alphabetic characters that are 
not part of character strings are mapped 
into their lowercase equivalent. The 
listing segment displays the segment as it 
appears after this mapping. Error messages 
refer to only the modified segment. 

The segment produced by -convert differs 
from the source segment as follows: 

1) Alphabetic characters not in character 
strings are mapped to lower case. 

2) Column 73-80 of the card image are 
deleted. Trailing blanks that are not 
part of a character string are 
el iminated. 



-subscr i ptrange 
-subrg 



-profile, -pf 
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3) Columns 1-6 have three different forms 
and are converted accordingly: 

a) Columun one contains a "C", "c" or "*". 
The card image is a comment and columns 
1-6 are preserved as is. 

b) Column 6 contains a character other than 
zero or blank. Columns 1 thru 6 are 
replaced by a tab and the preceding line 
is marked as being continued. 

c) For all other cards, column 6 is ignored 
and eliminated. Columns 1-5 can contain 
blanks or numerals. The numerals 
present are concatenated to form as a 
single string and are followed by a tab, 



The following control arguments are available, but are 
probably not of interest to the normal user. 



-time, -tm prints a table after compilation giving the 

time, in seconds, the number of page faults, 
and the amount of free storage used by each 
of the phases of the compiler. This 
information is also available from the 
command fort ran$t imes typed after a 
comp i 1 at ion . 

-debug, -db leaves the list-structured internal 

representation of the source programs intact 
after a compilation. This control argument 
is used for debugging the compiler, The 
command fort ran$ep i 1 ogue can be used to 
discard the list structure. 



-link -lk generates a link to the operator segment 

instead of loading its address from the 
stack. This control argument is provided 
for users who must be able to switch 
operator segments easily, and is not 
suggested for the general user because of 
increased execution overhead. 



Further information on the above control arguments is 
contained under Error D i agnost i cs and Listing . 
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Notes 

A normal compilation produces an object segment/ segnane, 
and leaves it in the user's working directory. If segname 
existed previously in the directory, its Access Control List 
(ACL) is saved and given to the new copy of segname. Otherwise, 
the user is given "re" access to the segment with ring brackets 
V,5,5 where V is the validation level of the process active when 
the object segment is created. 

The user's control arguments control the absence or presence 
of the listing segment for segname . fort ran and the contents of 
that listing. If created, the listing segment is named 
segname . 1 i st , The ACL is as described for the object segment 
except that it is given "rwa" access when newly created. 
Previous copies of segname and (if the list option is on) 
segname. list are replaced by the new segments created by the 
comp i 1 at ion . 

Note that because of the Multics standard which restricts 
the length of segment names, a FORTRAN source segment name cannot 
be longer than 2k characters. 

Er ror D i agnos t i cs 

The FORTRAN compiler can diagnose and issue messages for 
about 200 different errors. These messages are graded in 
severity as follows. 

Sever i tv Level Mean i ng 

1 Warning only - compilation continues without 
ill effect. 

2 Correctable error - the compiler remedies the 
situation and continues, probably without ill 
effect. For example, a missing end statement 
can be and is corrected by simulating the 
appending of the string "end" to the source to 
complete the program. This does not guarantee 
the right results, however. 

3 An uncorrectable but recoverable error. That 
is, the program is definitely in error and 
cannot be corrected but the compiler can and 
does continue executing up to the point just 
before code is generated. Thus, any further 
errors are diagnosed. 
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k An unrecoverable error. The compiler cannot 

continue beyond this error. The message is 
printed and then control is returned to the 
fortran command unwinding the compiler. The 
command writes an abort message into the 
"er ror_ou tput" stream and returns to its 
ca 1 1 er . 



Error messages are written into the stream "error__ou tpu t " as 
they occur. Thus / a user at his console can quit his compilation 
process immediately when he sees something is amiss. As 
indicated above, the user can set the severity level so that he 
is not bothered by minor error messages. He can also set the 
brief option so that the message is shorter. An example of an 
error message in its long form is: 

WARNING 156 IN STATEMENT 1 ENDING ON LINE 5 

Do loop control variable " j " has been modified within the 

range of the do loop ending at this statement. 

SOURCE: 5 continue 



If the brief option had been set the user would see instead: 

WARNING 156 IN STATEMENT 1 ENDING ON LINE 5 
j 

SOURCE: 5 continue 



Once a given error message has been typed on the user's 
console in the long form, all further instances of that error 
use the brief mode. 



If the listing option is on , the error messages are also 

written into the listing segment. They appear, sorted by line 
number, after the listing of the source program. Because of an 
implementation restriction, no more than 100 messages are printed 
i n the 1 i s t i ng . 



L i s t ? ng 



The listing created by fortran is a line-numbered image of 

the source segment. This is followed by a table of all of the 

names declared within the program. The names are categorized by 
declaration type which are: 



1) type, dimension, common statements, etc.; 

2) explicit context (labels, entries, and parameters); 



3 ) impl i c i t context . 
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Within these categories, the symbols are sorted 
alphabetically and then listed wi th their location, storage 
class, data type, attributes, and references. Then comes a 
listing of external operators used followed by a listing of the 
error messages. 

The object code map follows the list of error messages. 
This table gives the starting location in the text segment of the 
instructions generated for statements ending on a given line. 
The table is sorted by ascending storage locations. 

Finally, the. listing contains the assembl y- 1 i ke listing of 
the object segment produced. The executable instructions are 
grouped under an identifying header which contains the source 
statement which produced the instruction. Op code, 
base-register, and modifier mnemonics are printed alongside the 
octal instruction. If the address field of the instruction uses 
the IC (self-relative) modifier, the absolute text location 
corresponding to the relative address is printed on the remarks 
field of the line. If the reference is to a constant, the octal 
value of the first word of the constant is also printed. If the 
reference is to a variable, the name of the variable is printed. 
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flame : fort ran__abs, fa 

This command submits an absentee request to perform FORTRAN 
compilations. The absentee process for which fortran_abs submits 
a request compiles the segments named, appends the output of 
pr i nt_l i nk_i nf o for each segment to the segment segnamej_. 1 i st if 
it exists, and dprints and deletes segnamel. 1 i st . If the 
-ou tput_f i 1 e control argument is not specified, and output 
segment, segname. absout, is created in the user's working 
directory (if more than one segname is specified, the first is 
used). If the none of the segments to be compiled can be found, 
no absentee request is submitted. 

Usage 



fortran_abs segnamel. ... segnamea "f ort ran_control_args- 
-f ort ran__abs_control_args- 



1) segnamei 



2) f ortran__cont rol_args 



3) f ort ran_abs_cont rol_args 



-queue n, -q a 



is the path name of a segment to be 
compi 1 ed. 

can be one or more nonobsolete 
control arguments accepted by the 
FORTRAN compiler and described in 
fortran. (See the write-up in the 
MPM. ) 

can be one or more of the following 
control arguments: 

specifies in which priority queue 
the request is to be placed (n <= 
3). The default queue is 3. 
segnamei. 1 i st is also dprinted in 
queue a. 



-copy a/ -cp a 



specifies the number of copies (a 
<- k) of segnamei. 1 i st to be 
dprinted. The default is 1. 



-hold 



specifies that fortran_abs should 
not dprint or delete segnamei. 1 i st . 



-ou tput__f i 1 e _f, -of f_ 



specifies that absentee output is 
to go to segment f. where £ is a 
path name. 
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R o tes 

Control arguments and segment names can be mixed freely and 
can appear anywhere on the command line after the command. All 
control arguments apply to all segment names. An unrecognizable 
control argument causes the absentee request not to be submitted. 

Expanded segments containing include files are not deleted. 

Unpredictable results can occur if two absentee requests are 
submitted that could simultaneously attempt to compile the same 
segment or write into the same .absout segment. 

When doing several compi lat ions, it is more efficient to 
give several segment names in one command rather than several 
commands. With one command, only one process is set up. Thus 
the links that need to be snapped when setting up a process and 
when invoking the compiler need be snapped only once. 
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2/13/73 



Name : fs__chname 

The fs_chname command is an interface to the storage system 
subroutine hcs_$chname__f i 1 e. It causes an entry name of a 
specified segment to be replaced, deleted, or added. This 
command interprets none of the special command system symbols 
(e.g., *, >) and thus allows the user to by-pass the star 
convention or to manipulate strangely-named segments. For 
segments with ordinary names, the rename, addname and deletename 
commands perform the same function. See the MPM write-ups for 
these commands. 

Usage 

fs_chname di r_name entry_name oldname newname 

1) di rename is the directory name portion of the path name of 

the segment in question. 

2) entry_name is the entry name portion of the path name of the 

segment in question. 

3) oldname is an old entry name to be deleted. See Notes 

below. 

h) newname is a new entry name to be added. See Notes below. 

Notes 

When both an old entry name and a new entry name appear in 
the command line, the new entry name replaces the old entry name. 
This is equivalent to using the rename command. 

If the old entry name is a null character string (""), then 
the new entry name is added to the segment. This is equivalent 
to using the addname command. 

If the new entry name is a null character string (""), then 
the old entry name is deleted from the segment. This is 
equivalent to using the deletename command. 

The user must have write attribute on the directory 
containing the entry in order to make any name changes. 
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Examples 

fs_chname >my_dir alpha>beta alpha>beta alpha_beta 

This example would replace the incorrect entry name 
alpha>beta (which the rename command would interpret as 
designating the segment beta in the directory alpha) with a more 
appropriate name. 

fs_chname >my__dir story. equal 1111 story. = 

This example would add the entry name story. = to the 
specified segment. The addname command could not perform this 
operation because it would interpret the second component of 
story. = as use of the equals convention, and would attempt to add 
the entry name story. equal to the segment. See the MPM Reference 
Guide section, Constructing and Interpreting Names, for a 
discussion of the equals convention. 
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Command 
2/13/73 



N ame : get_com_« ine, gel 

The get_com_line command prints on the user's terminal the 
current value of the maximum expanded command line size. An 
expanded command line is one obtained after all active strings 
have been processed. 

Usage 

get_com_J i ne 

Note 

The default maximum length of an expanded command line is 
128 characters. It may be changed using the se t_com_l i ne 
command. For a discussion of the command language (including the 
treatment of active strings), see the MPM Reference Guide 
section, The Command Language. 
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Name : getquota, gq 

The getquota command returns information about the secondary 
storage quota and pages used for a specified directory. 

Usage 

getquota -ctl_arg- pathname!. ... pathnamen 

1) ctl_arg if -long or -lg, it specifies that the long form 

of output is to be used. 

2) pathname! is the name of the directory about which quota 

information is desired. If pathname! is -wd or 
-wdir, the working directory will be used. If no 
arguments are given, the working directory will 
be used. The star convention may by used to 
obtain quota information about several 
d i rector i es . 

Notes 

The short form of output (the default case) prints the 
number of pages of quota assigned to the directory and the number 
of pages used by the segments in that directory and any inferior 
directories that are charging against that quota. The output is 
prepared in tabular format, with a total, when more than one path 
name is specified. When only one path name is specified, a 
single line of output is printed. 

The long form of output gives the quota and pages used 

information provided in the short output. In addition, the 
number of immediately inferior directories with nonzero quotas is 
printed. The time-page product in units of page-days is also 
returned along with the date that this number was last updated. 
Thus, a user can see what secondary storage charges his accounts 
are accumulating. If the user has interior directories with 
nonzero quotas he will have to print this product for all things 
directories in order to obtain the charge. 
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10/18/73 



Name : help 

The help command assists users in obtaining information 
about commands and subsystems. 

Asking for help with a command causes information about that 
command to be printed on the the user's terminal. After a small 
but useful amount of information has been typed the user is asked 
if he wants more help. If the user replies "yes" another block 
of information is typed and the user again questioned. Otherwise 
the command exits. Typing the command "help" (or "help help") 
causes information about the help command to be typed. A count 
of the lines to follow is printed before each time the user is 
asked if the wants more help. 

Usage 

help -name- -cont rol__arg- 

1) name is the name of an information segment 

that the user wishes to read. it is 
the first component of a segment, in 
the installation information 

directory >documentat i on >iml_info or 
in the system information directory 
>documentat ion> i nf o, that has .info 
as its second component. If the name 
argument is present/ control_arg 
cannot be present. 

2) control_arg can be present only if the name 

argument is not present, and can have 
as its value: 

-pathname xxx, -pn xxx if this control argument is 

specified, help types the contents of 
the info segment whose path name is 
xxx instead of looking in the system 
or installation information 

d i rector i es . 

Sample 

In the following example, messages typed by the user are 
underlined for clarity but are not underlined in the actual 
scr i pt . 
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JmUi 

(5 1 i nes f ol low) 

7/28/72 - help now gives following line count in its question. 

The help command types out system information segments located in 
the directory >documentat ion> i nfo and installation information 
segments located in the directory >documentat ion>iml_info. 
Type "help name" to see the segment name. info. 

17 lines follow. More help? ves 

To see what system info segments are available, type 

list -pn >udd>documentat ion> i nfo *.info 
(There are currently over 200 info segments.) 

Some useful info segments are: 



motd message of the day 

news general information, on-line installations 

sys supervisor change Information 

pll status of PL/ I compiler 

fortran status of FORTRAN compiler 

basic status of BAS i C compiler 

bugs current list of system bugs 

doc documentation and assistance 

pt introduction to "per use_text", which gives 
additional information on many commands 



Rest of segment has 10 lines. More help? ves 

help accepts one control argument: 

-pathname xxx, -pn xxx if this control argument is 

specified, help types out the info 
segment whose path name is xxx, 
instead of looking in the system or 
information directory. If the suffix 
.info is missing from xxx, help 
appends it. 

Note 

The data segments are composed of blocks of ASCII character 
information, with the blocks arranged in descending order of 

importance of their contents. Lines should be less than 60 
characters long. Each block except the last is terminated by the 
ASCII character \006, which causes the help command to ask if 
more help is wanted. The first line of an info segment should 
contain a creation (or updating) date. 
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S tandard 



Command 
Service System 
02/12/71 



Name : hoi d, hd 

The hold command may be issued after a quit signal or an 
unclaimed signal has interrupted a process. This will cause the 
history of the process up to the point of interruption to be 
preserved. That is, the current state of the ca 1 1 -save-return 
stack is saved. This history is preserved until a release 
command is issued. 

Usage 

hold 



(END) 
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Command 

Standard Service System 

8/22/72 



Name : how_many__users, hmu 

This command tells how many users are on the system. In 
addition, it prints the name of the system, the load on the 
system, and the maximum load. If the absentee facility is up, 
the number of absentee users and the maximum number of absentee 
users is printed also. 



Usage 



how_many_users -ctl_arg.I- ... -ct l_argn- -argl.- ... -argn- 

cont rol 



1) ctl_argj_ 

-long, -Ig 



may be chosen from the following 
arguments : 

prints additional information including the 
name of the installation, the time the system 
was brought up, and the time of the last 
shutdown or crash. Load information on 
absentee users is also printed. 

-absentee, -as prints load information on absentee users 
only, even if the absentee facility is not 
runn i ng. 



-brief, -bf 
2) argi 

Name 

. Project 
Name. Project 

Notes 



suppresses the printing of the headers. Only 
used in conjuction with one of argj_. 

specifies that only selected users are to be < 
listed, and may be one of the following: 

lists a count of logged in users with user 
name "Name". 

lists a count of logged in users with a 
project ID of ".Project". 

lists a count of logged in users with the 
name and project of "Name. Proj ect" . 



Absentee counts in a selective use of how_many_users (i.e., 
when an argx is specified) are denoted by an asterisk (*). 



Up to twenty classes of selected users are permitted. 
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Example? 

1) Print summary information, 
hmu 

Multics 15.16 / load 5.0/50.0; 6 users 

2) Print summary information on absentee users, 
hmu -absentee 

Absentee users 0/2 

3) Pring long information, 
hmu -long 

Multics 15.16; MIT, Cambridge, Mass. 
Load = 2U.5 out of 50.0 Units; users = 23 
Absentee users = 0; Max absentee users = 2 
System up since 08/01/72 06Ul*.5 
Last shutdown was at 08/01/72 0517.9 

fc) Print brief information about the project SysDaemon. 
hmu -bf .SysDaemon 
SysDaemon =3+0* 

5) Print brief information about the person Smith, 
hmu -bf Smith 
Smith =1+1* 
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Command 
2/26/73 



Name ; indent, ind 

The indent command improves the readability of a PL/ I source 
segment by by indenting it according to a set of standard 
conventions described below. 



U.safte 



indent oldpath -newpath- -cont rol_args- 



1) oldpath 



2) newpath 



3) control_args 
-brief, -bf 

-lmargin XX, -lm XX 

-comment YY, -cm YY 



-indent ZZ, -in ZZ 



is the path name of the input PL/ I 
source segment. If the source segment 
name does not have a suffix of .pll, the 
suffix will be assumed. 

is the path name of the output PL/ I 
source segment. If the output segment 
name does not have suffix of .pll, the 
suffix will be assumed. If this 
argument is omitted, newpath will be 
assumed to be the same as oldpath, and 
the indented copy of the program will 
replace the original copy. 

may be any of the following; 

suppress warning comments on illegal or 
non-PL/I characters found outside of a 
string or comment. (Such characters are 
never removed.) 

set the left margin (indentation for 
normal program statements) to XX. If 
this argument is omitted, the default 
for XX is 11. 

set the comment column to YY. Comments 
are lined up in this column unless they 
begin a line and are preceded by a blank 
line (or are at the beginning of the 
program or are a comment beginning in 
column 1). If this argument is omitted, 
the default for YY is 61. 

set indentation for each level to ZZ. 
Each do, begin, proc, and procedure 
statement will cause an additional ZZ 
spaces of indentation until the matching 
end statement is encountered. If this 
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argument is omitted, the default for ZZ 
is 5 . 

Conventions 

Declaration statements are indented five spaces (with any 
identifiers that appear on extra lines, but which are still part 
of the same declaration, being lined up under the first 
identifier on the first line of the statement). Structure 
declarations are indented according to level number; after level 
two, additional levels are indented two more spaces each. 

Multiple spaces are replaced by a single space, except 
inside of strings or for non-leading spaces and tabs in comments. 
The indent command inserts spaces before left parentheses, after 
commas, and around the constructs =, ->, <=, >=, and . Spaces 
are deleted if they are found after a left parenthesis or before 
a right parenthesis. Tabs are used wherever possible to conserve 
storage in the output segment. 

The indent command counts parentheses and expects them to 
balance at every semicolon. If parentheses do not balance at a 
semicolon, or if the input segment ends in a string or comment, 
indent will print a warning message. Language keywords (do, 
begin, end, etc.) are recognized only at parenthesis level zero. 

Restr ictions^ 

Lines longer than 350 characters will be split, since they 
overflow indent's buffer size. This is the only case in which 
indent will split a line. 

Labeled end statements will not close multiple open do 
statements . 

The indent command assumes that the identifiers begin, end, 
procedure, proc, declare, and del are reserved words, and are 
always language keywords. Thus, indent will become confused if 
the input contains a statement like 

go to begin; 

since it will think that the statement delimits a begin block. 

Structure level numbers greater than 99 will not Indent 
correctl y . 
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Name : initiate/ in 

The initiate command enables users to initiate segments 
directly; i.e./ not using the normal search rules. For a 
discussion of search rules, see the MPM Reference Guide section. 
The System Libraries and Search Rules. 

Usage 

initiate pathname -refl- -ref 2_- ... -refn- -control_arg- 

1) pathname is the path name of the segment to be initiated. 

2) refj_ are optional reference names by which the segment 

may be known without further initiating. See 
Notes below. 

3) control_arg may be the string M -s" and may appear anywhere in 

the command line. If present/ the segment number 
assigned to the segment is printed on the user's 
termi nal . 

Notes 

if no reference names/ refj_/ are given in the command line, 
then the segment will be initiated by the entry name part of the 
path name. If any reference names/ refj_, are present in the 
command line, the segment will not be initiated by its entry 
name, but by the reference names so given. If the path name is a 
single element name then the directory assumed is the working 
directory. The < and > symbols are recognized in the path name; 

the star convention may not be used to initiate a group of 
segments . 

If a reference name cannot be initiated an error message is 
given and the command continues initiating the segment by the 
other names. 

To initiate a segment, the user must have non-null access to 
that segment. 
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Exampl es 

initiate >udd>m>mmm> gamma x y 

would initiate the segment >udd>m>mmm>gamma with the names x and 
y. 

initiate pop 

would initiate the segment pop in the working directory and give 
it the reference name pop. 

i n i t i ate xx u v -s 

would initiate the segment xx in the working directory with the 
reference names u and v and would print out the assigned segment 
number . 
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Command 

Standard Service System 

8/18/71 



Name : iocall 



Often it is useful to issue I/O system function calls from 
command level. The iocall command is provided for this purpose. 
It wi 1 1 perform the following functions: 1) it will accept a 
variety of argument formats, supplying useful default arguments 
where required; 2) it will print the values of return arguments; 
3) it will decode and print status returned by the I/O system. 

More information on I/O can be found in chapters 1 and 2 of 
the Introduction to Multics, the Reference Guide Section, and in 
the description of ios_. 



usage 



iocall f unct i on_name stream_name argument!. ... argumentn 



1) function name 



is one of the I/O system calls: abort, 
attach, changemode, detach, getsize, order, 
read, readsync, resetread, resetwrite, seek, 
setsize, tell, worksync, write, writesync. 



2) streamname 



is the stream_name argument present on all 
f unct ion cal 1 s . 



Notes 



Below is a list of the function calls accepted by iocall. 
The list starts with the complete I/O system call. Following the 
call is a list of the variations of the call acceptable by 
iocall. Following this are notes on special cases associated 
wi th the call . 



1) attach 



call ios_$attach ( st ream_name, type, dev i ce/s t ream__name, 
mode, status); 

iocall attach stream_name type dev i ce/s tream_name 
-model.- . . . -no den." 

The various mode_L are concatenated and separated by commas 
to form the mode argument. If there are no model/ mode is set to 
the null string. 
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2) detach 

call ios_$detach ( st ream_name, dev i ce/st ream__name, 
disposal/ status); 

iocall detach stream_name 

iocall detach stream_name dev i ce/s t ream_name 

iocall detach stream__name dev i ce/s treanwiame disposal 

If the arguments dev i ce/s t reanwiame or disposal are missing, 
the null character string is supplied. The status argument is 
supplied and decoded. 

3) read 

call ios_$read ( st reanwiame, workspace, offset, nelem, 
nelemt, status); 

iocall read stream_name segment 

iuca.i read stream_name segment nelem 

iocall read stream_name segment offset nelem 

The offset and nelem arguments, if present, are in decimal. 
If the offset argument is missing, 0 is supplied. If the nelem 
argument is missing, the maximum size of the segment argument is 
provided as a multiple of the current element size. A pointer to 
the base of the segment argument is supplied as the workspace 
argument. If the segment argument does not exist, it is created 
in the working directory. The status argument is supplied and 
decoded . 

k) write 

call ios_$write ( st ream_name, workspace, offset, nelem, 
nelemt, status); 

iocall write stream_name 

iocall write stream_name segment nelem 

iocall write stream_name segment offset nelem 

The offset and nelem arguments, if present, are in decimal. 
If the offset argument is missing, 0 is supplied. If the nelem 
argument is missing, the bit count of the segment argument is 
provided as a multiple of the current element size. A pointer to 
the base of the segment argument is suppl ied as the workspace 
argument. The status argument is supplied and decoded. 
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5) seek 

call ios_$seek ( st ream_name, ptrnamel, ptrname2 / offset, 
status) ; 

local 1 seek stream_name ptrnamel 

iocall seek st ream__ name ptrnamel ptrname2 

iocal 1 seek streanwiame ptrnamel ptrname2 offset 

The offset argument, if present, is decimal. If the offset 

argument is missing, 0 is supplied. If ptrname2 is missing, 

"first" is supplied. The status argument is supplied and 
decoded . 

6) tell 

call ios_$tel 1 ( st ream_name, ptrnamel, ptrname2, offset, 
status ) ; 

iocall tell stream_name ptrnamel 

iocall tell st ream_name ptrnamel ptrname2 

If ptrname2 is missing, "first" is supplied. The offset 
argument is supplied and its value is printed in decimal on 
return. The status argument is supplied and decoded. 

7) setsize 

call ios_$setsize ( st ream_name, elementsize, status); 
iocall setsize stream_name elementsize 

The elementsize argument is decimal. The status argument is 
supplied and decoded. 

8) getsize 

call ios_$getsize ( st ream_name, elementsize, status); 

iocall getsize stream_name 

The elementsize argument is provided and its value is 
printed in decimal on return. The status argument is supplied 
and decoded. 
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n \ -1 ~ - 

v j u r uc i 

call ios_$order ( s t ream_name, request/ argptr, status); 

iocall order stream_name request 

The argptr argument is supplied as a null pointer. The 
status argument is supplied and decoded. 

10) changemode 

call i os_$changemode ( st ream__name, mode, old_mode, status); 

iocall changemode st ream_name -model.- ... -moden.- 

The various modes are concatenated and separated by commas 
to form the mode argument. If there are no mode_L, mode is set to 
the null character string. The old_mode argument is supplied and 
its value printed on return. The status argument is supplied and 
decoded. 

11) resetread 

call ios_$ reset read ( st reanwiame, status); 
iocall resetread stream_name 
The status argument is supplied and decoded. 

12) resetwrite 

call ios__$resetwr i te ( st ream_name, status); 
iocall resetwrite stream_name 

The status argument is supplied and decoded. 

13) abort 

call ios_$abort ( st ream_jiame, old_status, status); 

iocall abort stream_name 

A zero bit string is supplied as the old_status argument. 
The status argument is supplied and decoded. 

Ik) readsync 

call ios_$ readsync ( st ream_jiame, smode, limit, status); 
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iocal 1 readsync stream_name smode 
iocall readsync st ream_name smode limit 

The limit argument is in decimal, if present, and is set to 
a large value if absent. The status argument is supplied and 
decoded. 

15) writesync 

call ios_$wr i tesync (streanwiame, smode, limit, status); 

iocall writesync stream_name smode 
iocall writesync stream_name smode limit 

The limit argument is decimal, if present, and is set to a 
large value if absent. The status argument is supplied and 
decoded. 
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Name : i omode 

The i omode command changes the type of code conversion 
performed by the I/O system for a specified device. 

Usage 

iomode mode -ioname- 

1) mode specifies the type of code conversion. It may be 

"edited" or "normal". The edited mode suppresses 
all escapes; i.e., non-available graphics. The 
normal mode includes escapes. 

2) ioname specifies the stream name associated with the 

device whose mode is to be set. If ioname is not 
specified the stream name "user_putput" is assumed. 
For the normal user this will have the effect of 
setting the mode of his terminal. 

Note 

Other modes are available in the I/O system and may be set 
by using the iocall command (with the changemode function) or the 
i os_$changemode subroutine. See the MPM write-ups for iocall and 
ios_. The iomode command merely calls i os_$ changemode to make 
the change. 
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Name : line_length, 11 

The line_length command allows the user to control the 

maximum length of a line written on the device which his process 

is using for output on the "user_output" I/O stream. This device 
will usually be his terminal. 

Usase 

line_length maxlength 

1) maxlength is the maximum number of characters which may 
henceforth be printed on a single line using the 
I/O stream "user^output". In most cases, this is 
the maximum length of a line of output printed at 
the user's terminal. 
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Name : 1 i nk, 1 k 

The link command causes a storage system link with a 
specified name to be created in a specified directory pointing to 
a specified segment or directory. For a discussion of links / see 
the MPM Reference Guide section/ Segment/ Directory/ and Link 
Attr i butes. 

Usage 

link pathll path21 pathln -path2n- 

1) pathli specifies the segment to which path2X is to point. 

2) path2j. specifies the link to be created. If not given (in 

the final argument position of a command line only) 
a link to pathli. will be created in the working 
directory with the entry name portion of pathlj_ as 
i ts entry name. 

Notes 

Entry names must be unique within directories. Therefore/ 
if the creation of a link would lead to a duplicate name, the 
user is interrogated as to whether he wishes the entry bearing 
the old instance of the name to be deleted. If not/ the link 
will not be created. 

The star and equals conventions may be used. 

The user must have append access in the directory in which 
the link is to be created. 

Exampl e 

link >my_dir>beta alpha >di ct i onary >gr ammar 

creates two links in the working directory/ named alpha and 
grammar; the first points to the segment beta in the directory 

>my d f r and the second points to the segment grammar in the 

directory dictionary. 
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Name : 1 i sp 



The lisp command invokes a LISP subsystem that provides an 
interpreter of the MACLISP dialect of LISP for interactive use on 
Mul t i cs . 



LISP is a recursive language that is suited for many 

applications. The Mul tics implementation is designed to be very 
fast yet not limited by storage capacity as many other LISP 

systems are. Over two hundred fifty system functions are 

provided for diverse user needs while a compiler is provided so 

that a user can compile his own functions from functions written 
for interpretive use. 



Usflfie 



lisp -pathname- -argument!.- -argument]!- 

1) pathname is a path name of a saved environment from which 
the subsystem constructs an initial active 
environment. If not specified, the standard LISP 
saved environment is used. The user can save an 
environment from inside the LISP subsystem and 
then use this saved environment at some later time 
to initialize a new lisp command to the same state 
as when he saved it. 



2) argument! is an arbitrary argument which can be referred to 
from within the LISP subsystem with the 
appropriate system function. 

Note? 

For a complete description of the MACLISP dialect of LISP, 
consult the document LISP Reference Manual ( MACLISP Dialect ). 
The file lisp. info describes methods for obtaining this document 
in addition to other useful information. Also, refer to the MPM 
write-up for the Multics command, 1 i sp_comp i 1 er . 



This MPM write-up is divided into two parts with the first 
part describing the basic structure of the interpreter and the 
methods by which the user can control it while the second part 
summarizes some of the characteristics that distinguish the 
MACLISP dialect from other dialects of LISP. Both parts assume 
that the user has some prior knowledge of LISP, such as having 
read Weissman's LISP 1.5 PRIMER or part of the LISP 1.5 Manual . 
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Part J_: Essential Facts iQL Using the Interpreter 
Accompl i sh i ng Evaluation 

Explanations in the following text are illustrated by an 
example of a terminal session. Line numbers have been added for 
reference and a star is placed after the numbers for lines that 
have items entered by the user. 



1* 


1 i sp 




2 


* 




3* 


(cons (quote a) 


(quote b)) 


k 


(a . b) 




5* 


(car (quote (a b 


c d))) 


6 


a 




7* 


321*5 




8 


3245 




9* 


(setq foo (quote 


bar)) 


10 


bar 




11* 


foo 




12 


bar 




13* 


(quit) 




lk 


r U10 1.471* 9. 


261* 201* 



When the lisp command is issued, an initial environment of 
atoms, functions, and list structure is constructed from a saved 
environment. After this environment has been constructed, the 
interpreter reaches its basic state, known as top level. 
Whenever the interpreter reaches this state from some other state 
it outputs a star to the user's terminal as is seen in line 2. 
MACLISP has an eval type top level as opposed to some other 
dialects of LISP that have an evalquote type top level. Thus the 
user must tYPe one. form _to be eya1e4 fol lowed bx a_ new 1 ine 
character . instead of two S-express i ons, one to be applied as a 
function to the second. Note that one has to explictly quote an 
S-expression if one does not want to have it evaluated. On line 
3 the user types a form that is a simple function call. The 
evaluation is printed on line t*. Lines 5 and 6 illustrate the 
same thing. On line 7 the user simply types a number followed by 
a new line character. Numbers evaluate to themselves which is 
shown on 1 ine 8. No te that j_£ ±s_ very easy lo forget that His. 
interpreter starts oy_t operating in base eight, octal . * I n 



♦The input radix can be varied by resetting the system variable, 
ibase, and the output radix can be varied by resetting the 
variable, base. 



(c) Copyright, 1973, Massachusetts 

and Honeywel 1 



Institute of Technology 
Information Systems Inc. 



MULT ICS PROGRAMMERS 1 MANUAL 



1 i sp 



Page 3 
8/13/73 



MACLISP, atoms that can have values are called symbols. On line 
9 the user sets the symbol, foo, to have the value, bar. Then on 
line 11 the user evaluates this symbol. Finally we give a simple 
example of control of the interpreter. In order to leave the 
subsystem permanently one uses the function quit which takes no 
arguments. This is illustrated above by line 13. All atoms and 
list structure that have been created by the user are then 
destroyed and the subsystem returns control to Multics. 

Control of Ihe_ Interpreter 

A MACLISP interpreter gives a user a great amount of control 
over its behavior. It has many switches that can be set by the 
user and functions that he can replace. Some of these features 
are discussed in Part II. Many of the switches can be set in two 
different ways, either by using some function or by a general 
method that has real time effect. This latter method is 
described immediately below. 

If at any time the user depresses the interrupt (break or 
attention) key on his terminal, the LISP interpreter responds by 
prompting the user and then waits for input. The user can then 
type a single letter command fol lowed by. a qew 1 ine character . 
It must be stressed that these commands have effect in real time, 
they happen when they are given and not after the interpreter is 
finished doing whatever it was doing at the time the attention 
key was depressed. Three important commands are: 

z gives the user a Multics Command Processor at a higher stack 
frame. This is identical to what happens in most Multics 
programs when the interrupt key is depressed. The Multics 
command, start, starts lisp running again in the standard 
manner. If the command, program_i nter rupt, is issued, then 
lisp again prompts the user, but only accepts the three 
characters mentioned on this page. 

g interrupts the current LISP program and returns control to 
the top-level function of the interpreter. The internal 
LISP stacks are unwound and temporary bindings of variables 
are restored. 

b enters a "break loop", a read-eval -pr i nt loop at a higher 
level in the LISP stacks. The user can examine variables, 
do whatever else he wishes to do and then return to the 
previously running program by typing the atom, 
<dol lar-s ign>p ($p). 
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Error Condi tions 

If the user tries to evaluate some item that causes a LISP 
error, the interpreter usually creates a break loop and informs 
the user of this by typing something such as ";bkpt unbnd-vrbl " . 
In many cases the user can then modify the incorrect item and 
then restart the program. However, for now it is sufficient to 
know that if the user types the atom, $p, the interpreter returns 
to top level and the user can try again. 



Part 1 I : Features o_f £h& MACLISP Dialect 
Features Common 1P_ ALL MAQUSP UnpJ ementations 

1) Debuggi ne System As the name, lisp subsystem, implies, a 
MACLISP interpreter provides a complete system in which to work. 
Thus one of its important features is a sophisticated debugging 
system. Functions are provided to set break-points, do traces, 
do back traces, examine variables at various levels in the LISP 
stack, reset variables, examine arguments in function calls, 
return values for function calls that are still stacked up, and 
others. In addition, as mentioned in Part I, most errors 
signalled by the interpreter are correctable from the break loop 
created by the error. These break loops are created by the 
user interrupt system that is mentioned below. 

2) Rea 1 Time Control Characters A method is provided for 
giving commands from the console to the interpreter while it is 
also doing evaluation. 

3) Programmable Portions of £h£ Interpreter Many parts of 
the interpreter can be modified by the user. Besides offering 
versatility for regular programming, this facilitates the use of 
LISP as a language for implementing other languages and 
subsystems. For example, the languages Micro^Planner and 
CONNIVER and the mathematical laboratory, MACSYMA, are all 
written in LiSP. 

Reader Syntax Tabl e The syntax categories of characters 
can be set by the user. 

Macro Characters — One of the things that can be entered in 
the syntax table is whether or not a character is a macro 
character. When the reader encounters a macro character, it 
invokes a function associated with that character. For 
example the system comes supplied with two macro characters, 
<accent-acute> (') which is the quote macro and <semi-colon> 
(;) which is the comment macro. When the reader sees 
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1 <S-express ion> 

the associated function for the macro character 1 transforms 
it into 



(quote <S-express ion> ) 



when a <semi-colon> is encountered the associated function 
discards the rest of that line. 

Mul ti pi e Obarravs Instead of a single obarray (or oblist 
as it is known in other LISP's) several may be used. The 
user can create new obarrays, either totally or 
incrementally different, and then instruct the LISP reader 
to use a particular one. This allows use of modular systems 
by preventing name conflicts. 

Var i abl e Top- 1 eve 1 Function — The user can set the 
top-level function to be anything. For example the user 
could make an evalquote top level. 

User I nterruot Functions -- On the occurrence of certain 
conditions such as various errors, an alarmclock ringing, or 
certain real time control characters being entered, the 
interpreter executes various user interrupt functions. For 
example many of the error interrupts are preset to a 
break-loop producing function. The user has the ability to 
set any of the user interrupt functions. 

k) Arbi trarv Preci sion Ar i thmet i c -- In addition to a large 
number of arithmetic functions including exponential and 
trigonometric functions, MACLISP'S arithmetic capabilities are 
further enhanced by the ability to do integer arithmetic to 
arbitrarily large precision. 

5) Comoi 1 ed Code — Due to the structure of the interpreter, 
the code produced by the compiler is very efficient as compared 
to other dialects of LISP. Refer to the MPM write-up for the 
Mul tics command, 1 i sp_comp i 1 er . 

Features Specific 1P_ Ihe Mul tics Implementation 

1) The entire address space of the Mul tics virtual memory can 
be used for LISP storage. 

2) Functions can be written in the other languages that exist 
on Mul tics. 
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3) A new data type called character strings exists, and 
functions are provided to manipulate them. 
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Name : 1 i sp_compi 1 er, lep 



The 1 i sp_comp i 1 er command invokes a compiler that translates 
a file of LISP functions written for interpretive use into a 
standard Multics object segment. These compiled functions can 
then be used from within an actively running LISP. 

Usag e 

1 i sp_compi 1 er -pathname- -cont rol_.arg.l- ... -cont rol_argn_- 



1) pathname 



2) control_argi 
-time, -tm 



-total_time, 
-total, -tt 

-nowarn, -nw 



is the path name of a segment or 
mul t i -segment file to be compiled. If the 
name does not end in .lisp, the suffix is 
supplied. This file can contain function 
definitions, declare f s, and other LISP code 
which will be executed when the object 
segment is made known to the LISP environment 
by the fasload function. 

can be chosen from the following list of 
control arguments: 

prints out the time taken to compile each 
function. 

at the end of the compilation, prints out the 
CPU time, paging, etc. 

do not print warning messages. 



-pathname xxx , the following argument ( xxx ) is the path name 
-pn xxx . -p xxx of the segment to be compiled. This control 

argument specifies that the name should be 
used exactly as given. The .lisp suffix is 
not appended to it, and it can begin with a 
minus sign without adverse effect. 



-al l_speci al 
-macros, -mc 



-genprefix xxx , 
-gnp xxx 



make all variables "special". 

copy macro definitions into the output so 
that they will be defined at run time. 

Sets the prefix for generated function names 
to xxx . 
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-check/ -ck 



do not generate an object segment, just check 
for errors. 



eval xxx 



evaluate the S-expression 
beginning the compilation. 



xxx 



before 



Notes 



The object segment created by this command is placed in the 
working directory with a name which is the first component of the 
name of the source file; i.e., the name of the source file up to 
but not including the first period. 

Include files can be used by inserting the statement: 



The include file name . i ncl . 1 i sp is inserted into the input at 
that point. The standard include file search rules are used (see 
the MPM Reference Guide section, The System Libraries and Search 
Rules) . 

For a complete description of the MACLISP dialect of LISP, 
consult the document L ISP Reference Manua 1 ( MAC LI SP D ial ect ) . 
The help segment lisp. info describes methods for obtaining this 
document in addition to other useful information. Also, refer to 
the MPM write-up for the Multics command, lisp. 



(^include name) or (^include " 



name 
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Name : list/ Is 

1 i stotal s, 1 1 
1 i stnames, 1 n 

The list command enables the user to determine the names 
(including multiple names), modes, times last used and modified, 
and lengths of either all the entries in a specified directory or 
selected entries. The related listotals and listnames commands 
give information only about counts and lengths, and names, 
respectively. ■" All three commands present information about 
segments, directories, mul t i -segment files, and links (in that 
order, where appropriate), and respect various options as to 
searching and sorting, as explained below. 



Usage : list, Is 
1 i st ent ry.1 
1) entryl 



entryn. -opt_l- 



2) opt! 



-pathname, -pn 



-segment, -sm 



i s an 
opt ion 
entries 
ent r i es 



-optn" 

entry name (see the -pn 
for a directory). If no 
are specified, all the 
of the relevant directory 



are dea It wi th . 

is chosen from the^ tfql 1 ow i ng list 
of options (see also- Notes below): 

uses the directory specified in the 
immediately following path name. 
The desired entries follow the path 
name. The default is the current 
working directory. -pn may occur 
more than once in a single 
invocation of the command. Entries 
preceding the first -pn refer to 
the working directory. (See 
Exampl es below.) 



lists segments only, 
is on. 



The default 



-directory, -dr 



•mul t i segment_f i 1 e 
•msf 



1 i sts 
defaul t 



d i rector i es 
i s off . 



lists mul t i -segment 
The default is off . 



only. The 



files on 1 y . 
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1 ink, -Ik 



i s - *. ^ i : ^ i, _ ~ ~ i . , 

I I :> c O i i i i r\ o uii i y 



off. 



-branch, -br 



-all, -a 



date, 
•dtu 



time used 



date, 
•dtm 



time modified 



lists branches, 
segments, directories, 
mul t i -segment files only, 
def aul t i s off . 



e. , 

and 
The 



lists all segments, directories, 
mul t i -segment files, and links. 
The default is off . 

sorts on and prints the date and 
time last used. The order 
is reverse chronological, i.e., 
the most recent first. The 
default is of f . 

sorts on and prints the date and 
time last modified. The order is 
reverse chronological, i.e., the 
most recent first. The default is 
off. 



-reverse, -rv 



reverses the order (to 

chronological or least recent 
first) for the -dtu or -dtm 
options. If -dtu is wanted, only 
-rv need be given. The default is 
off. 



Notes 

In the discussion of options, default means "what is assumed 
if this option is not given for a particular invocation of the 
command", on means the specified action is taken, off means the 
specified action is not taken. 



I i nks . 



The last three options (-dtu, -dtm, -rv) do not apply 



to 



The star convention may be used in the entryj. argument. 



Conflicting options (e.g., -dtu and 
given in a single invocation of the command, 
and -Ik do not conflict. 



-dtm) should not be 
Note that -sm, -dr, 
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Examp] es 



list -a - rv 



would list all the segments, directories, mul t i -segment files, 

and links in the current working directory, with the segments, 

directories, and mul t i -segment files sorted on the date and time 
last used, in chronological order. 

list a b -pn >udd>Mul t i cs>Doe *.pll -pn >udd>MAC>Roe ** 

would list segments a and b (if present) in the working 
directory, all two component segments with a second component of 
pll in the directory >udd>Mul t i cs>Doe, and all of the segments in 
the directory >udd>MAC>Roe. 

Usage : listotals, It 

listotals entryl. ... entryn. -optl.- ... -optn- 

1) entryj. as above. 

2) optj. as above except that the last three options are not 

valid (-dtu, -dtm, and -rv). 

The response is a count of, and the total number of records 
occupied by, segments, directories, and mul t i -segment files, and 
a count of links, as appropriate to the particular options 
chosen . 



Usage : listnames, In 



listnames entryl. ... entryn. -optl.- ... -optn- 

1) entryj. as above. 

2) optl as above except that the last three options are not 

valid C-dtu, -dtm, and -rv). 

The response is a list of the names of the segments, directories, 
mul t i -segment files, and links, as appropriate to the particular 
options chosen. 
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Name : 1 i st_abs_reques ts, lar 



The 1 i st_abs_reques ts command allows the 
information about absentee requests. Normally the 
allowed information only concerning requests which 



user to obtain 
use r will be 
he has made. 



Usage, 



1 i st__abs_reques ts option! 



opt i onn 



I) optioni 



is selected from 
options and may 
command 1 i ne : 



the following list of 
appear anywhere on the 



total, -tt 
long, -lg 



-queue n, -q n 



-all, -a 



indicates that the user wants only the 
total of the requests in the queue. 

indicates that all of the information 
pertaining to an absentee request will be 
printed. If this option is omitted, only 
the full path name of the absentee control 
segment will be printed. 

indicates which queue is to be searched. 
It must be followed by an integer 
specifying the number of the queue. If 
this option is omitted, the third priority 
queue is searched unless the -all option 
is provided. (See below.) 

indicates that all priority queues are to 
be searched starting with the highest 
priority queue and ending with, the lowest 
priority queue. 



Note 

The -total and -long options are incompatible. 
Fxamples 

1) 1 i s t_abs_reques ts 

Queue 3: 3 requests. 6 total requests. 

>udd>Mul t i cs >J one s> dump > t ran si a te . abs i n 
>udd>Multics>Jones>abs>tasks.absin 
>udd>Mu 1 1 i cs >Jones>abs >b i nd i ngs . abs i n 
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2) 1 i s t_abs_reques ts -long -queue 1 



Queue 1: 2 requests. 27 total requests. 



Absentee input segment: 
Restar tabl e : 
Deferred time: 
Argument string: 



"pll" 
"abed 



yes 

09/16/71 2300.0 edt Thu 



>udd>M>Day >dump> t rans 1 ate . abs i n 



"-table" 
"-map" 



Absentee input segment: 
Restartable : 
Cpu limit: 

Absentee output file: 



>udd>M>Day >b i nd>au to__b i nd . abs i n 
no 

oOO seconds 

>udd>M>Day>bi nd>bd.out 



3) 1 i s t_abs__reques ts -total -all 

Queue 1: 2 requests. 15 total requests. 
Queue 2: 0 requests. 0 total requests. 
Queue 3: 0 requests. 39 total requests. 
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Name : 1 I st_daemon_reques ts, Idr 

The 1 i st_daemon_requests command prints on the user's 
terminal information about dprint and dpunch requests. Normally 
the user is allowed to obtain information concerning only 
requests which he has previously made. See the MPM command 
write-ups for dprint and dpunch. 



Usage 



1 i st_daemon_requests control _arg! 



-cont rol_arga~ 



1) control_argl 



is selected from the following list of 
cont?*ol arguments and can appear anywhere 
in the command line: 



total, -tt 
long, -Ig 



-queue Hz ~Q a 



-all, -a 



indicates that the user wants only the 
total of the requests in the queue. 



indicates that 
pertaining to a 
If this control 
the f ul 1 path 



all of the information 
request should be printed, 
argument is omitted, only 
name of the segment to be 
printed or punched is printed. 



indicates which queue is to be searched. 
It must be followed by an integer 
specifying the number of the queue. If 
this control argument is omitted, only the 
third priority queue is searched unless 
the -all control argument is provided. 
(See below. ) 

indicates that all priority queues are to 
be searched starting with the highest 
priority queue and ending with the lowest 
priority queue. 



Note 

The -total and -long control arguments are incompatible, and 
cannot be used in the same 1 i st_daemon_reques ts command line. 
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1) 1 i st_daemon__requests 

Queue 3: 3 requests. 6 total requests. 

>Jones_di r>dump> trans late. list 
> Jones_d i r>doc> 1 dr . runoff 
>Jones_di r> Jones . prof i le 

2) 1 i st_daemon_requests -long -queue 1 

Queue 1: 2 requests. 27 total requests. 



Pathname: >Smi th_d i r>foo. 1 i st 

Type: print 

Copies: 1 

Delete: yes 

For: Jones 

Pathname: >doc> i nf o>motd . i nf o 

Type: print 

Copies: 3 

Delete: no 

To: 575 Tech Sq. 



3) 1 i st_daemon_requests -total -all 

Queue 1: 2 requests. 15 total requests. 
Queue 2: 0 requests. 0 total requests. 
Queue 3: 0 requests. 39 total requests. 
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Name : 1 i st_i acl_di r, lid 

This command lists some or all of the entries on a directory 
Initial Access Control List (Initial ACL) in a specified 
directory. A directory Initial ACL contains the ACL entries to 
be placed on directories added to the directory. For a 
discussion of Initial ACLs, see the MPM Reference Guide section/ 
Access Control. 

Usage 



listacl pathname acnamel 



acnamen -con trol_arg- 



1) pathname 



specifies the directory in which the 
directory Initial ACL should be listed. If 
it is "-wd"/ "-working_di rectory" or omitted 
then the working directory is assumed. If it 
omitted then no acnamel may be specified. 
The star convention may be used. 



2) acnamel 



is an access control name. If no acnamel is 
specified then the whole Initial ACL will be 
listed, acnamel must be of the form 
person. project. tag. Any components missing 
on the left must be delimited by periods; 
however/ the periods may be omitted on the 
right. If one or more of the components is 
missing then all access names that match the 
given components will be listed. If acnamel 
is "-a" then the whole Initial ACL will be 
1 isted. 



3) control_arg 



may be -ring (-rg). It may appear anywhere 
on the line and affects the whole line. If 
present it must be followed by a digit, where 
0 <. digit <. 7/ which specifies which ring's 
Initial ACL should be listed. If the control 



argument 
assumed. 



s not given then the user's ring is 
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Exarop 1 es 

1 i s t_i acl_di r all_runoff .Faculty Fred 

will list, from the directory Initial ACL in the directory 
all_ runoff, all entries with the project name Faculty and all 
entries with the person name Fred. 

1 i d -wd -a - rg 5 

will list all entries in the directory Initial ACL for ring 5 in 
the working directory. 
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Name : 1 i st_i aci_seg, lis 



This command lists some or all of the entries on a segment 
Initial Access Control List (Initial ACL) in a specified 
directory. A segment Initial ACL contains the ACL entries to be 
placed on segments added to the directory. For a discussion of 
Initial ACLs, see the MPM Reference Guide section. Access 
Contro 1 . 



Usage 



listacl pathname acnamei. ... acnamen. -control_arg 



1) pathname 



specifies the directory in which the segment 
Initial ACL should be listed. If it is 
M -wd", "-worki ng_di rectory" or omitted then 
the working directory is assumed. If it is 
omitted then no acnamei may be specified. 
The star convention may be used. 



2) acnamei 



is an access control name. If no acnamei is 
specified then the whole Initial ACL will be 
listed. acnamei must be of the form 
person . project . tag. Any components missing 
on the left must be delimited by periods; 
however/ the periods may be om i tted on the 
right. If one or more of the components is 
missing then all access names that match the 
given components will be listed. If acnamei 
is "-a" then the whole Initial ACL will be 
1 i s ted. 



3) control_arg may be -ring (-rg). It may appear anywhere 

on the line and affects the whole line. If 
present it must be followed by a digit, where 
0 <. digit <. 7, which specifies which ring's 
Initial ACL should be listed. If the option 
is not given then the user's ring is assumed. 
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Exampl es 

1 i s t_i acl_seg a11_runoff .Faculty Fred 

will list/ from the segment Initial ACL in al l_runof f , all 
entries with the project name Faculty and all entries with the 
person name Fred. 

1 i s -wd -a -rg 5 

will list all entries in the segment Initial ACL for ring 5 in 
the working directory. 
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liame : 1 i st_ref_names , 1 rn 



This command accepts both segment numbers and pathnames and 
prints the reference names and segment numbers by which segments 
are known. Uhen segment numbers are specified, it also prints 
pathnames . 



Usage 

1 i st__ref_names aJL . . . an 



1) aj_ can be segment numbers, pathnames, or 

op t i ons . 

If ai is a segment number, the pathname and reference names 
of segment aj_ will be printed. 

If a_L is a pathname, the segment number (in octal) and the 
reference names of segment ax will be printed. If aj_ looks like 
an option (i.e., if it is preceded by a minus sign) or a number, 
then aj. should.be preceded by -name or -nm. 

The following options are available for use with this 
command : 



-from j_ These two options allow one to specify a 

-to k. range of segment numbers (segments j_ through 

k.) . The pathnames and reference names of the 
segments in this range are printed. If the 
-from option is omitted, the segment number 
of the first non-ring 0 segment will be 
assumed, unless -all is used (see below). If 
the -to option is omitted, the highest used 
segment number will be assumed. 

-brief, -bf This option suppresses printing of the 

reference names for the entire execution of 

the command. This option may appear anywhere 
i n the line. 



all, -a This option causes the pathnames and 

reference names of al 1 known segments to be 
printed, as well as the reference names of 
ring 0 segments. This option may appear 
anywhere in the line. The -a option is 
equivalent to -from 0. 
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Notes 

All of the above forms (segment numbers/ pathnames/ and 
options) may be mixed. For example: 

1 i st_ref_names pathone 156 -from 230 

In the above command line, the segment number (in octal) and the 

reference names of pathone are returned. The pathname and 

reference names of segment 156 and of all segments from 230 on 
are also returned. 

If called with no arguments, 1 i s t_ref_names prints 
information on non-ring 0 segments only. 



(c) Copyright, 1971, Massachusetts Institute of Technology 

All rights reserved. (END) 



MULT I CS PROGRAMMERS' MANUAL 



1 i stacl 



Command 
2/28/73 



i stacl , 



la 



This command lists some or all of the entries on 
Control List (ACL) of either a segment or directory. 



an Access 



Usage 



li stacl -pathname- -acnamel- 



-acnamen- -cont ro l_arg- 



1) pathname 



specifies the segment or directory for which the 
ACL should be listed. If it is "-wd", 
■'-worki ng__di rectory" or omitted, then the working 
directory is assumed. If it is omitted then no 
acnameX may be specified. The star convention may 
be used. 



2) acnamej_ 



is an access control name. If no 
specified then the whole ACL will 



acnamej_ i s 
be listed. 



acnamej. must be of the form 
Any components missing on 
delimited by periods; however, 
omitted on the right. If 
components is missing then all 
match the given components 
acnamei is "-a" then the whole 



person . pro ject . tag. 
the left must be 
the periods may be 
one or more of the 
access names that 
will be 1 i sted. I f 
ACL will be 1 i sted. 



3) control__arg may be -r i ng__brackets (-rb). It may appear 
anywhere on the line and affects the whole line. 
If it is present, the ring brackets will be 
listed. Ring brackets are discussed in the MPM 
Subsystem Writers 1 Guide section, Intraprocess 
Access Control (Rings). 

Exampl es 

listacl noti ce. runoff .Faculty Doe 

will list, from the ACL of not i ce . runoff , all entries with the 
project name Faculty and all entries with the person name Doe. 

la *.pl 1 -rb 

will list the whole ACL and the ring brackets of every segment in 
the working directory that has a two-component name with second 
component pll. 
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Command 



tyame ; login, 1 

The login command is used to gain access to the system, 
login is actually a request to the answering service to start the 
user identification and process creation procedures. Therefore/ 
this command can only be issued from a terminal connected to the 
answering service; that is, one which has just dialed up, or one 
which has been returned to the answering service after a session 
terminated with a "logout -hold" command. 

The login command will request a password from the user (and 
will attempt to insure either that the password does not appear 
at all on the user's terminal or that it is throughly hidden in a 
line of cover-up characters). The password is a string of one to 
eight letters and/or integers associated with the person ID. It 
is maintained by the system administration. 

After the user responds with his password, the system will 
look up the person ID, the project ID, and the password in its 
tables, and verify that the person ID is valid, that the user is 
a legal user of the project, that the project ID is valid and 
that the password given matches the registered password. If 
these tests succeed, and if the user is not already logged in, 
the load control mechanism is consulted to determine if allowing 
the user to log in would overload the system. 

If the user is permitted to log in, a process is created for 
the user, and the terminal is placed under control of the new 
process . 



Usage 



login person -project- -contro l_args 



1) person 



is the user's registered personal 
identifier. This argument must be 
suppl i ed. 



2) project 



is the identification of the user's 
project. If this argument is not 
supplied, the default project ID 
associated with the person ID will be 

assumed. See the 

-change_def aul t_project control 
argument below for changing the 
default project ID to the project ID 
specified by this argument. 
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3) control_args 
-brief, -bf 



home_dir path, 
hd path 



process_overseer path, 
po path 



-no_pr i nt_of f , -npf 



may be selected from the following: 

Messages associated with a successful 
login will be suppressed. If the 
standard process overseer is being 
used, then the message of the day is 
not printed. 



set 
t 



The user's home directory will be 
to the path specified, if the user's 
project administrator allows him to 
specify his home directory. 

The user's process overseer will be 
the procedure given by the path 
specified, if the user's project 
administrator allows him to specify 
his process overseer. 

The system will overtype several 
lines to provide a black area for the 
user to type his password. 



-print_off, -pf 



-no_preempt, -np 



-no_star t_up, -ns 



-account id, -ac id 



-force 



The system will not overtype several 
lines for the password, since the 
user's terminal responds to the 
printer off control sequence. 

If the user can only be logged in by 

preempting some other user in his 

load control group then the login 
does not take place. 



If the user 
segment, 
admi ni strator 
avo id » t, 



has a start__up.ec 
and the project 

allows the user to 
instruct the standard 



process overseer not to execute it. 



Replace the normal account identifier 
with id. (This option 
effect . ) 



for the user 
currently has 



no 



If the user has the guaranteed login 
attribute, log the user in if at all 
possible. Only system users who 
perform emergency repair functions 
will have the necessary attribute. 
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Request to change the user's password 
to a newly given password. The login 
command will request the old 
password, and then a new password. 
If the old password is correct, the 
new password will replace the old for 
subsequent logins, and the message 
"password changed" will be printed at 
the user's terminal. Note that the 
user should not type the new password 
as part of the control argument. 

-change_def aul t_ project, Request to change the user's default 
-cdp project ID to be the project ID 

specified in this login command line 
(see the description of the second 
argument above). If the password 
given by the user is correct, the 
default project ID will be changed 
for subsequent logins, and the 
message "default project changed" 
will be printed at the user's 
terminal. 

Notes 

Several parameters of the user's process, as noted above, 

can be controlled by the user's project administrator. The 

project administrator may allow the user to override some of 

these attributes by specifying control arguments in his login 

line. See the MPM Reference Guide section, Protocol for Logging 

In, for more information about these variable parameters and 
thei r usual val ues . 



-change_password, 
-cpw 



© 
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Name : logout 



The logout command terminates a user session and ends 
communication with the Multics system. 



Usage 

logout -con t ro l_args 



1) control__args is an optional control argument that can be 

chosen from the following: 

-hold the user's session is terminated. However, 

communication with the Multics system is not 
terminated and a user can immediately log in 
wi thout red i a 1 i ng. 



-brief/ -bf no logout message is printed, and if the 

-hold control argument has been specified, no 
login message is printed either. 



Note 



See also the MPM Reference Guide section, The Multics 
Command Language Environment. 
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Name : mail, ml 

The mail command allows the user to send a segment to 
another user or to print messages sent to him. Mail sent to a 
user is placed in the segment "mailbox" in his home directory. 
The mailbox is provided with a lock. 

Usgfie 

mail -path- -personl- -project!- ... -persona" -projectn- 

1) path is the pathname of a mailbox segment to be printed 

(if no personJL project! pairs are supplied) or of 
a segment to be sent to other user or users (when 
one or more person! projectj. pairs are specified). 

2) person! is the name of a person to whom mail is to be 

sent . 

3) projectj. is the name of a project on which person! works. 
Pr i nt i ne Ma i 1 

The mailbox segment named by path will be locked and its 
contents printed out preceded by a line of the form 

x messages, y 1 i nes 

If path is omitted, the segment "mailbox" in the user's home 
directory is printed. After the mail is printed, the mail 
command will ask whether to delete the mail. If the answer is 
no, the command mail unlocks the mailbox and terminates it; if 
the answer is yes, mail truncates the ma i 1 box ^to. ze.ro length. 

Sending M^ii 

The contents of the segment path will be copied into the 
segment 

>user_di r_d i r>projectj_>personj_>ma i 1 box 

for each person-project pair specified. When mail is sent, the 
command first locks the target mailbox and then copies the 
contents of the mail into the target mailbox, preceded by a 
header identifying the sender: 

From Person . Proj ect date time 
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The segment to be mailed must be less than one record long. 
Illegal characters will be removed from the mail as it is sent. 

If path is */ mail will respond "Input" and accept lines 
from the keyboard until a line with only a period (.) is typed; 
the typed lines then will be sent to the specified addresses. 

Mote 

The user of the mail command must have rwa access to any 
mailbox he accesses/ and e access to the directory superior to 
the mailbox in order to read or send mail. 

Entry : mail$unlock 

The user will receive a message of the form 



mail: The segment is already locked. 

mailbox busy/ try again later. 

if the mailbox he attempts to access is locked. Because quitting 
out of mail may leave a mailbox locked/ this entry is provided to 
force the lock to zero. The mailbox specified by path will have 
its lock cleared. If path is not specified/ the mailbox in the 
user's home directory will be unlocked. 



Usage 

mail$unlock -path- 

1) path as above. 

Creating & Mai lbox. Segment: 

In order to receive mail/ there must be a segment in the 
user's home directory called mailbox whose ACL is set to rwa for 
all users. To create such a segment perform the following 
sequence of commands in your home directory. 



create mai 1 box 

setacl mailbox rwa *.*.* 
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Name : make_peruse_tex t, mpt 

In order that the peruse_text command may perform 
efficiently, it is necessary to translate a source segment 
(document) which is written for use with peruse_text. This 
translation produces a segment comprised of the original text 
followed by some information used by peruse__text to access a 
labeled title without performing a line-by-line search. 

Usage 

make_peruse_text pathname 

1) pathname specifies that the segment pathname. pts is the 
source segment. The resulting new segment will be 
placed in the user's working directory under the 
name en tryname . pt, where entryname is the entry 
name portion of pathname. 

No tes 

When writing an on-line document for use with peruse_text, 
the writer should pay particular attention to the formatting of 
the document title and the topic headings. A sample outline of a 
typical document is given at the end of this description. 

1) Title of Document 

The first line must be the title of the document. When 
peruse_text is first invoked, or when the call or return 
requests are issued, peruse_text searches for the first "new 
line" character, then prints the line ended by this "new 
1 ine" character. 

2) Topic Headings 

Each topic in a document is introduced by a labeled title 
similar to a topic heading in an outline. These topic 
headings consist of the ASCII character \006, immediately 
followed by a label (see Label Syntax below), followed by a 
space or spaces and the title of the topic. The complete 
topic heading must be written on one line. 

3) Label Syntax 

Each topic heading in a peruse_text document begins with the 
ASCII character \006, and is immediately followed by a 
label. A label is composed of a sequence of from one to 
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eight integer elements separated by periods (e.g., 1., 3.1, 
U.1.12). A label must contain at least one period. Each 
integer element can take on values between 0 and 511. The 
integer elements of topic headings must be in ascending 
sequence from the start of the document to the end of the 
document. However, they do not have to be consecutive 
integers; numbers can be skipped. If make_peruse_text finds 
errors in label format or sequence, it prints diagnostic 
messages and aborts the translation of the segment specified 
by pathname. 

h) Recommended Style 

It is recommended that topic headings should be followed by 
some associated text which describes the topic, and/or refer 
the user to other topics. If the inclusion of associated 
text does not seem appropriate, then the topic heading is 
probably unnecessary. The format of this text is at the 
discretion of the user, but should be terse. 

First level topics should have single-level labels, i.e., 
1., 2., not 1.0, 2.0, etc. Topic headings (excluding the 
label) and the document title should usually be all capital 
letters. Numbers are permitted in both. 

Each topic heading that is subordinate to another topic 
should be indented one more space than its immediately 
superior topic heading. This can be achieved by inserting 
one or more blank characters before the ASCII \006 
character . 

To prevent excessive printing at the terminal, no single 
topic should be divided into more than five subtopics at the 
next subordinate level. In addition, the number of lines of 
text following a topic heading should be on the order of 
six. 

Lines should be no more than 72 characters long, so that 
they may fit on one line of all commonly used terminals. 
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Sample 

FILE OUTPUT, CONSOLE OUTPUT (6-2-71) 

1. FILE OUTPUT COMMAND 
1.1 USAGE 

1.3 DEFAULT 

l.k FEATURES AND CONSTRAINTS 

1.5 EXAMPLE 

2. CONSOLE OUTPUT COMMAND 
2.1 USAGE 

2.1* FEATURES AND CONSTRAINTS 

2.5 EXAMPLE 
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Name : memo 

The memo command makes possible the use of Multics as an 
interactive notebook and reminder list containing memos. It 
allows the user to specify a maturity time for each memo (a time 
before which the memo will not appear). By use of the alarm 
feature the user can specify the exact time the memo will be 
printed on the console. Memos can also be set which are passed 
directly to the command processor and executed as a normal 
Multics command line. Using these features jointly the user can 
set a memo which, rather than reminding him to do something at a 
certain time, actually performs the action itself. Finally the 
user can specify that the memo is to be repeated at regular 
i nterval s . 

In the default case memo maintains its information in a 
segment Username. memo in the user's home directory. If memo is 
invoked and such a segment does not exist, memo attempts to 
create and initialize it. Optionally a different memo segment 
can be specified and used. Each memo in the memo segment 
consists of a text portion containing up to 132 characters, the 
maturity date, and additional information telling whether the 
memo is to be repeated or not and whether is to be printed or 
executed . 

For the user's convenience, control arguments allow the 
printing, listing, and deletion of memos selected by subsequent 
optional arguments. Memos can be selected by number, type, 
maturity time and content. Other control arguments enable or 
disable memo alarms. 

It should be noted that if a date, time, repeat interval, or 
match string contains embedded blanks, that string must be 
enclosed in quotes so that the command processor will pass it to 
memo as a' single argument. 



Usage 



memo -cont rol_arg- -optl; 



-opt jn- -memo__text- 



1) control_arg 



is one of the following control 
arguments. Only one can appear on the 
command line, and it must be the first 
argument. If no control argument 

appears then if nothing else appears on 
the command line mature memos are 
printed or executed, otherwise the rest 
of the line is used to set a memo. 
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-pathname memopath 



pti ineniOpatn 



-list/ -Is 



where memopath is the path name of a 



Tho on(- y \i name 



of the segment must end in the suffix 
.memo, and if the segment does not 
exist, memo attempts to create it. If 
the user does not specify the suffix 
.memo, it is assumed. 

memos selected by the optional arguments 
are printed in full detail, including 
their maturity times, text, and 
information about the optional 
arguments, opti, used when the memos 
were set. No memos are executed. 



-print, -pr 



the text of all memos selected by the 
optional arguments, opti, are printed. 
No memos are executed. 



-delete, -dl 

-off 



al 1 memos 
arguments, 



selected by the 
opti, are deleted. 



opt i onal 



suppresses all memo alarms. This 
control argument must not be followed by 
any optional arguments, opti. 



-on 



-brief 



2) opti 



memo number 



enables the setting of memo alarms. 
This control argument must not be 
followed by any optional arguments, 
opti. 



suppresses the message 

are, found, T 
not be foil owe 

arguments, opti. 



none 
must 



;d 



"No memos" if 



s, control 
by any 



argument 
opt i onaT 



is one of the following optional 
arguments. Note that some of the 
arguments can be used for setting memos, 
some for selecting memos to be printed, 
listed, or deleted, and others for both 
setting and selecting memos. 

is used when selecting memos. If any 
numbers are used to specify which memos 
are to be selected then only those memos 
which match one of the numbers are 
sel ected . 
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•date memo_time 
dt memo_time 



time memo__time 
tm memo time 



-alarm, -al 



repeat interval 
rp interval 



-invisible, i v 



-cal 1 



where memo_time is a time in a form 
suitable for input to the subroutine 
convert_date_to_bi nary_ (see the MPM 
subroutine write-up for 

convert_date_to_b i nary , ) memo_ time is 
truncated to midnight preceding the date 
in which memo_time falls. If used while 
setting a memo then the trucated 
memo__time becomes the maturity time of 
the new memo. If memos are being 
selected, then only those memos with 
maturity times prior to or equal to the 
truncated memo_time are selected. 

where memo_time is a time in a form 
suitable for input to the subroutine 
convert_date_to__b i nary_. This optional 
argument is used in the same manner as 
the -date optional argument above except 
that memo_time is not truncated. 

if a memo is being set. this specifies 
that the memo is to be an alarm. When 
mature it will be printed or executed 
immediately (or as soon as alarms are 
enabled) and then deleted. If memos are 
being selected, this argument selects 
only those memos which are alarms. 

where interval is the interval 
(>=1 minute) at which this memo is to 
appear. This optional argument is used 
when setting a memo. When the memo is 
mature an identical memo is set with a 
maturity time that is interval in the 
future. The interval specification 
should be in the format of the offset 
field suitable for input to 

convert_date_to_b i na ry_. 

used only when setting a memo, this 
optional argument specifies that the 
memo will never be mature and will never 
be printed during a normal memo print. 

used only when setting a memo, this 

argument specifies that the memo is to 

be passed to the command processor as a 
command . 



c) Copyright, 1973, Massachusetts Institute of Technology 

and Honeywel 1 Information Systems Inc. 



memo 



MULTICS PROGRAMMERS' MANUAL 



Page h 



-match string!. 



s t r i ng£L 



where stringx is a character string. 
Memos containing substrings matching all 
of the stringi's are selected. The 
remainder of the line is interpreted as 
the set of the strings to be matched. 
The maximum number of strings which may 
be specified is 32, and the maximum 
length of any one string is 32 
cha racters . 



3) memo_text 



is the text of the memo being set. 



Notes 



If the -pathname control argument is used, the following 
argument must be the path name of a memo segment which is to be 
used. If a memo segment is specified by this means it will 
continue to be used for the duration of the user's process, 
unless changed again by the -pathname control argument. If the 
segment with path name memopath does not exist, memo attempts to 
create it. 

To set a memo, no control arguments are given. Any of the 
optional arguments except -match and memo_number may be used to 
specify the type of memo being set, and the time it will mature. 
If no maturity time or date is specified, the maturity time is 
assumed to be the current time. 

If memo is invoked with no arguments or only the -brief 
control argument, then all mature memos are printed or passed to 
the command processor. Alarms are enabled and any alarms pending 
are printed or executed. 

If either the -print or -list control argument is given, 
then all memos selected by the optional arguments are printed. 
The contents of the memo segment do not change in any way, and 
memos that would ordinarily be passed to the command processor 
are printed instead. If no optional arguments are used to select 
which memos are to be printed or listed, then all memos are 
printed or listed. If the -date or -time optional arguments are 
given, then only those memos which mature before the specified 
date or time are printed. Only those memos are printed which 
meet all of the specifications set by the optional arguments. 

If the -delete control argument is used, memos selected by 
the optional argument are deleted. If no optional arguments have 
been used to specify which memos are to be deleted, then none are 
del eted . 
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The -off control argument is useful for times when the user 
does not wish any extraneous output/ such as when using the 
Multics runoff command. The command line "memo -on" may be given 
to re-enable alarms after they have been turned off, or it may be 
used at login time to enable alarms without printing or executing 
other mature memos. Memo alarms are enabled by any use of memo 
except "memo -off". 

Examples 

In the following sequence of memo examples, input typed by 
the user is marked by an arrow (->). Ready messages from the 
system are omitted. First, the user's memo segment is 
initialized and is demonstrated to have no mature memos. Four 
memos are set and then listed, first in their entirety, then only 
mature memos, then all memos maturing before a specified date. 
Finally, the only mature memo is deleted, and its successful 
deletion is demonstrated. 

->memo 

memo: Creating >udd>xproj >Jones>Jones .memo. 

->memo 

No memos. 

->memo get bookshelves 

->memo -date 5/23/73 -repeat 2weeks -alarm Staff meeting at two. 
->memo -call -date 6/1/73 -repeat lmonth list -dtm -rev 
->memo -time thu9am -repeat lweek Weekly report due Friday. 

->memo -list 

1) Tue 05/15/73 1729 get bookshelves 

2) Wed 05/23/73 0000 Staff meeting at two. (alarm, "2weeks") 

3) Fri 06/01/73 0000 list -dtm -rev (call, "lmonth") 

h) Thu 05/17/73 0900 Weekly report due Friday, ("lweek") 

->memo 

1) get bookshelves 

->memo -print -date 5/30/73 
get bookshelves 
Staff meeting at two. 
Weekly report due Friday. 

->memo -delete -match book 

->memo 

No memos . 



(c) Copyright, 1973, Massachusetts Institute of Technology 

and Honeywell Information Systems Inc. (END) 



MULT ICS PROGRAMMERS 1 MANUAL 



move 
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Command 
Service System 
4/3/72 



Name : move, mv 



The move command causes a designated segment (and its access 
control list (ACL), and multiple names, if any) to be moved to a 
new position in the storage system hierarchy* 



usage 

move pathll path21 ... pathla path2& -ca- 

1) pathll is the path name of the nondi rectory storage 

system segment to be moved. 

2) path2j_ is the path name to which pathll is to be 

moved . 



3) ca may be the following control argument: 

-brief, -bf causes the messages "Bit count inconsistent 

with current length..." and "Current length 
is not the same as records used..." to be 
suppressed. 



Notes 

The star and equal conventions may be used. 



if path21 already exists, the user will be interrogated as 
to whether he wishes it to be deleted. 

The user's mode with respect to the directory portion of 
path21 must include execute, write, and append access. 

Exampl e 

move alpha >udd>Mul t i cs >Doe>= >udd>Mul t i cs>Doe>beta b 

causes segment alpha to be moved from the current working 
directory to the directory >udd>Mul t i cs>Doe, with the name alpha, 
and segment beta to be moved from the directory >udd>Mul t i cs >Doe 
to the current working directory, with the name b. 
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Command 

Standard Service System 

6/23/71 



. I ame : movequota/ mq 

The movequota command allows a user to move all or part of a 
quota between two directories (one immediately inferior to the 
other) . 

Usage 

movequota pathname!. quota_changel. ... pathnamen. quota_changea 

1) pathname! is the pathname of a directory branch. The 

quota change will take place between this 
branch and its parent directory. "-wd" may 
be given to specify the working directory. 
The star convention may not be used. 

2) quota_changej_ is the number of pages to be subtracted from 

the parent di rectory quota and added to the 
quota on pathnamel. If this number is 
negative/ the number of pages will be added 
to the parent directory quota and subtracted 
from the quota on pathname!. 

Notes 

The user must have "write" permission on both the directory 
specified by pathnamel and its parent directory. 

After the change/ the quota must be greater than or equal to 
the number of pages used in pathnamel unless the change would 
make the quota zero. 

If the change would make the quota on pathname! zero, there 
must be no immediately inferior directories with nonzero quota. 
When the quota is changed to zero, the pages used and the 
page-time product for pathnamel is then reflected up to the 
superior directory. 

Example, 

movequota >udd>Multics 1000 >udd>Mul t i cs> Doe -50 

will add 1U00 pages to the quota on >udd>Multics and subtract 
1000 pages from the quota on >udd. It will then subtract 50 
pages from the quota on > udd>;tul t i cs>Doe and add 50 pages to the 
quota on >udd>Mul t i cs . 



(END) 
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Command 
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Name: names 

Entry : names$move 

This command moves all the "extra" names from one multiply- 
named directory entry to another for any number of entry pairs. 
The name used to designate the segment is not moved; all others 
are moved. 

Usage 

names$move from_pathl to_pathl from_path2 to_path2 ... 
from_pathN to__pathN 

1) from_pathi is the pathname of the segment whose names 

are to be moved. 

2) to_pathi is the pathname of the segment to which names 

are to be moved. 

Entry : names$copy 

This entry is similar to names$move but leaves the names on 
the segment which originally has them. Note that in this case 
the names cannot be copied to a segment in the same directory 
because that would attempt to duplicate names in the directory. 
All of the names on the original segment are copied. 

Usage. 

names$copy from_pathl to_pathl ... from_pathN to_pathN 
arguments as described above. 



(END) 
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Command 
Service System 
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Name : new__proc 

The new__proc command creates a new process for the user/ 
leaving him at command level in the same working directory he 
logged into. Although not implemented in the initial release of 
Multics, the process from which the command was invoked will in 
later versions be available for debugging. 

The new_proc command is typically used to refresh static 
storage, possibly because a runaway program has overwritten the 
static storage area. Since dynamically snapped links are placed 
in the static storage area, they must be resnapped in the new 
process. 

If the login working directory contains a segment named 
start_up.ec/ new__proc will cause the command 

exec_com star t__u p new_proc 

to be automatically issued in the new process. This feature may 
be used to initialize per-process static variables. 

Usage 

new_proc 



(END) 
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Command 

Standard Service System 

5/10/72 



Name : page_trace/ pgt 



This command prints a recent history of page faults and 
other system events within the calling process. 



.Usage 

page_trace -count- — long- 



1) count 



causes the last count of system events (mostly 
page faults) recorded for the calling process to 
be printed. If count is not specified/ then all 
the entries in the system trace list for the 
calling process will be printed. Currently/ there 
is room for approximately 350 entries in the 
system trace list. 



2) -long/ -Ig 



causes full path names to printed, where 
appropriate. The default is to print only entry 
names . 



Output 



The first column of output describes the type of the trace 
entry. If nothing is printed in this column for an entry, the 
entry is for a page fault. The second column of output is the 
real time, in milliseconds/ since the previous entry's event 
occurred. The third column of output is the page number for 
entries where this is appropriate. The fourth column gives the 
segment number for entries where this is appropriate. The last 
column is the entry (or path) name of the segment for entries 
where this is appropriate. 

Whenever the real time between successive entries is greater 
than one second/ a blank line is printed between the entries. 
This blank line usually appears between interactions, where the 
user interposes a think time longer than one second, and on long 
running programs, between scheduling quanta. 



Notes 



To perform useful tests to determine page fault activity and 
frequency, the prepaging mechanism must first be crippled for the 
calling process. This is because the prepage driving list is the 
same list as the page trace list. To turn prepaging off, the 
command 
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P r e_page_of f 

may be issued. To turn prepaging on again / the command 

pre__page_on 
may be issued. 

Note that since it is possible for segment numbers to be 
reused within a process/ and since only segment numbers (not 
names or path names) are kept in the trace array, the entry names 
and path names associated with a trace entry may not be correct. 
In fact, the entry and path names printed are the current ones 
appropriate for the given segment number. 

For completeness/ events occurring while inside the 
supervisor are also listed in the trace. The interpretation of 
these events sometimes requires detailed knowledge of the system 
structure; in particular/ they may depend on activities of other 
users. For many purposes, the user wi 1 1 find it appropriate to 
identify the points at which he enters and leaves the supervisor, 
and ignore the events in between. 

Typically/ any single invocation of a program will not 
induce a page fault on every page touched by the program, since 
some pages may still be in primary memory from previous uses or 
use by another process. It may be necessary to obtain several 
traces to fully identify the extent of pages used. 
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Name : peruse__text 



The peruse_text command allows a user to extract information 
from a formatted segment with a minimum of printing at the 
terminal. Formatted segments consist of a labeled topic heading 
for each block of text. To write and prepare such a segment/ 
refer to the MPM description of the make_peruse_tex t command. 

The peruse_text command responds by printing the title line 
of the document. 



Usage 

peruse__text 

1) control_arg 

2) entryname 



-control__arg- entryname 

is an optional argument which specifies, if 
present, that entryname is actually a path 
name. It can have as its value either 
-pathname or -pn. 

refers to the segment entryname.pt in the 
specified directory. The suffix .pt need not 
be specified. If the -pathname control 
argument is used, the complete path name is 
specified by this argument. Otherwise, it is 
assumed that entryname.pt resides in the 
directory where all pt documents are kept, 
>documentat ion>pt (abbreviated as >doc>pt). 



label Syntax, ajnd Lapel Depth 

Each topic in a document is introduced by a topic heading 
which begins with a label. A label is composed of a sequence of 
from one to eight integer elements separated by periods (e.g., 
1., 3.1, 4.1.12). A label must contain at least one period. 
Each integer element can take on values between 0 and 511. The 
number of integer elements in a label is the depth of the label, 
ranging from one to eight. In the above examples of a label, the 
depths are 1, 2, and 3 respectively. 



Subsystem Request List 

The peruse_text command responds to requests to peruse topic 
headings and associated text. These requests are listed in the 
fol lowing table. 
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Request 
t 

P 
i 

c 



Meaning; 

.table 

OX i nt 

index 
c_al 1 



r return 
"string" find 

q qu i t 

Tab! e Request 



Func t i on 

print a table of the topic 
depth 

print the specified range 
with their associated text 
print the specified 
call from the segment 
to peruse a specified 
return to perusing 



headings at one 
of topic headings 



range of topic headings 
currently being perused 
segment 

the segment that was 
perused before the current segment 
print all topic headings where the specified 
character string appears as part of the topic 
heading or the associated text 
exit peruse_text to command level 



The table request prints a table of the topic headings at 
one depth. The format is: 

t - label - 

If no argument is given, all topic headings with a depth of one 
are printed. If a label is supplied, all topic headings one 
level deeper than and subordinate to the specified label are 
printed. The space between t and the argument is optional. 

Whenever the table reques-t causes the last topic heading at 
the level specified to be printed, peruse_text appends a line 
containing only the word END after the last topic heading. When 
a topic heading has no subordinate topic headings, an asterisk 
appears on the same line, following the topic heading. 

See Exampl es below for use of the table request. 



I ndex and Pr i n t Requests 

The index request prints topic headings within 
specified. The print request prints topic headings 
associated text within the range specified. The 
requests is: 



the range 
and the 
format of these 



reques t_n ame 

1) request_name 

2) begin_label 



begin_label- -end_label- -depth- 
is either i or p 



specifies the first label to 
printed. This argument is 



be indexed or 
opt i onal ; i ts 



default value is the current label (that is, 
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the value of the label last tabled, indexed, 
or printed). 



3) -end label 



specifies the last label to be indexed or 
printed. It must be preceded by a hyphen. 
It is optional and has as a default value the 
value of begin_label. 



h) depth 



specifies the depth of topic headings and 
text to be indexed or printed. That is, it 
specifies the maximum number of integer 
elements in labels to be indexed or printed. 
It is optional and takes the maximum of the 
depths of begin_label and -end_Jabel as its 
default value. 



Spacing in the index and print request is not significant 
before the begin_ label and -end_label arguments. However, one 
or more spaces must appear before the depth argument when it is 
present. 

As in the table request, a line consisting of the word END 
is printed following the last topic heading at a given level. 
Requests for indexing or printing which do not involve the last 
topic heading produce 

no such line. However, unlike the table request, no asterisk 
appears on the line with topic headings having no inferiors. 

Note that the depth specified (or assumed by default) may be 
larger than the depth of -end_label. In this case, printing of 
output will continue past the topic heading specified by 
-end_label until ail topic headings inferior to that one and 
having a depth within the specified range are printed. 

See Exampl es below for various ways of using the index and 
print requests. 

Use of Aster i sk i n an Argument 

An asterisk (*) has special meaning in arguments to the 
table, index, and print requests. It is taken as a shorthand 
notation for the maximum possible value of the place it occupies. 
Thus, an asterisk is equivalent to 511 when used as an integer 
element in a label argument, and is equivalent to 8 when used as 
a depth argument. 

Note that the use of asterisk in the table request is nearly 
always meaningless since very few documents will have an integer 



(c) Copyright, 1972, Massachusetts Institute of Technology 
All rights reserved. 



peruse_tex t 



MULT ICS PROGRAMMERS' MANUAL 



Page h 



element of a label equal to 511. (Recall that the table request 
says to print all topic heading immediately inferior to a 
specifed label.) Similarly, the use of asterisk in the 
begin_label argument of the index and print requests is usually 
meaningless. Its usefulness is in the -end_label and depth 
arguments of the index and print requests where it effectively 
specifies that the request should be performed until the end of 
the document is reached and should go to the maximum label depth 
present in the document. 

Def aul t Request N ame s 

The table, print, and index requests are the only ones 
concerned with the structure of the document being perused. The 
peruse_text command remembers which of the three was last used, 
and supplies it whenever the request name is omitted from a 
request. The default request name is thus the last request (of 
those three) used for the document being perused. Upon initial 
entry to each document, the default request is index. 

F i nd Request 

The peruse_text command accepts any quoted string (including 
spaces) as a request. The find request causes peruse_text to 
search the segment being perused for all occurrences of the 
quoted string and to print the labeled topic headings wherever 
the quoted string occurs in the title or associated text. The 
format of the find request is: 

"string" 

The value of the quoted string may be any ASCII string that might 
be part of the contents of the segment currently being perused. 
The ASCII string must be enclosed in quotation marks. The PL/I 
quoting convention is used if quotation marks are to be specified 
within the quoted string. 

Cal 1 and Return Requests 

The call request is used to change from perusing the current 
segment to perusing another segment. The return request is used 
to resume perusing the previous segment. 
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The format of the call request is. 

c -control_arg- entryname 

Arguments are the same as those for peruse_text. The title line 
of the called segment is printed immediately following the call. 

The format of the return request is. 

r 

The title line of the segment returned to and the topic heading 
last referenced before the call request are printed upon return. 
The default request name is set to t, p, or i, whichever was the 
default at the time of the call request. 

Qui t Request 

The quit request may be used to exit peruse_text to Multics 
command level. The format of the .guit request is: 

q 

Program interrupt 



The user may interrupt peruse__text by pressing the QUIT 
button, especially during the printing of unwanted output. To 
immediately return to pe ruse__tex t, where peruse_text waits for a 
subsequent request, type the command program_i n ter rup t (pi). 

Exampl es 

The following series of requests was performed (in the order 
shown) on the pt segment for the peruse_text command. A short 
explanation of the feature being demonstrated by each request 
precedes the request. The line typed by the user is marked by a 
small arrow (->) at the left. The rest was printed by 
peruse__text . The print request was slighted in the examples due 
to the excessive space required. However, examples of the index 
request cover the print request format adequately. 
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1) Obtain a full table of contents of the document for reference 
in later examples. incidentally this shows the index request 
with three arguments, and the asterisk in arguments. 

->i 1. -*. * 

1. PREFACE 

1.1 FUNDAMENTALS OF PERUSE_TEXT 

1.2 TO READ THE REST OF THIS DOCUMENT 

2. PERUSE_TEXT (pt) COMMAND 

2.1 USAGE 

2.2 OPTION 

2.3 DEFAULTS 

2.1* FEATURES AND CONSTRAINTS 

2.4.1 LABELS 

2.4.2 TABLE (OF CONTENTS), INDEX AND PRINT REQUESTS 

2.4.3 THE CALL AND RETURN REQUESTS 

2.4.4 THE FIND REQUEST 

2.4.5 THE QUIT REQUEST 

2.4.6 USE OF ASTERISK 

2.4.7 DEFAULTS FOR ARGUMENTS 

2.4.8 DEFAULT FOR REQUEST NAMES 

2.4.9 PROGRAM INTERRUPT 

2.4.10 DOCUMENT FORMAT 

2.4.11 "COMPILATION" OF DOCUMENTS 
2.5 EXAMPLES 

END. 

2) Table request with no arguments. 
->t 

1. PREFACE 

2. PERUSE_TEXT (pt) COMMAND 
END. 

3) Default request name (i.e., the table request is assumed). 
->2. 

2.1 USAGE * 

2.2 OPTION * 

2.3 DEFAULTS * 

2.4 FEATURES AND CONSTRAINTS 

2.5 EXAMPLES * 
END. 

4) Index request with no arguments. 
->i 

2.5 EXAMPLES 
END. 
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5) Index request with begin_label argument only. 
->i 2.4.2 

2.4.2 TABLE (OF CONTENTS), INDEX AND PRINT REQUESTS 

6) Index request with begin_label and -end_label arguments. Note 
that no space appears before -end_label. 

->i 1.-2. 

1. PREFACE 

2. PERUSE_TEXT (pt) COMMAND 
END. 

7) Index request with all arguments. All optional spaces are 
omi tted. 

->il.-2. 2 



1. PREFACE 

1.1 FUNDAMENTALS OF PERUSE_TEXT 

1.2 TO READ THE REST OF THIS DOCUMENT 

2. PERUSE_TEXT (pt) COMMAND 

2.1 USAGE 

2.2 OPTION 

2.3 DEFAULTS 

2.k FEATURES AND CONSTRAINTS 

2.5 EXAMPLES 
END. 



8) Index request (assumed by default) with the -end_label 
argument missing and an asterisk for the depth argument. 

->1. * 

1. PREFACE 

1.1 FUNDAMENTALS OF PERUSE_TEXT 

1.2 TO READ THE REST OF THIS DOCUMENT 

9) Print request with no arguments. 
->P 

1.2 TO READ THE REST OF THIS DOCUMENT 

Use the requests described in Section 1.1 to read the rest 
of this document. 
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10) Find requests. 



->"request" 

1.1 FUNDAMENTALS OF PERUSE_TEXT 

1.2 TO READ THE REST OF THIS DOCUMENT 
2. PERUSE_TEXT (pt) COMMAND 

2.4 FEATURES AND CONSTRAINTS 

2.4.2 TABLE (OF CONTENTS), INDEX, AND PRINT REQUESTS 

2.4.3 THE CALL AND RETURN REQUESTS 

2.4.4 THE FIND REQUEST 
2. I*. 6 USE OF ASTERISK 

2.4.7 DEFAULTS FOR ARGUMENTS 
2.1*. 8 DEFAULT FOR REQUEST NAMES 
2.4.9 PROGRAM INTERRUPT 

2.5 EXAMPLES 

-/►"REQUEST" 

2.4.2 TABLE (OF CONTENTS), INDEX, AND PRINT REQUESTS 

2.4.3 THE CALL AND RETURN REQUESTS 

2.4.4 THE FIND REQUEST 

2.4.5 THE QUIT REQUEST 

2.4.8 DEFAULT FOR REQUEST NAMES 



11) Call request, and index request showing initial default 
request name. 

- >c ec 

EXEC_COM (5-17-72) SSS 

->1.1 -1.5 



1.1 USAGE 

1.3 DEFAULTS 

1.4 FEATURES AND CONSTRAINTS 

1.5 EXAMPLES 
END. 



12) Return request showing that the current label is restored. 
->r 

PERUSE__TEXT ( 5-17-72) 
1.2 TO READ THE REST OF THIS DOCUMENT 

Summary of Requests 

1) Data Requests 

t Print first-level table of 

contents . 

t label Print topic headings at next 

level subordinate to label. 
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i begin_label 

i begin_label -end_label 

i begin_label -encMabel depth 



P begin_labe1 

p begin_Jabe1 -end_label 

P begi n_l abel -end__label depth 

"string" 

2) Control Requests 
c name 

c -pathname name 



Print current topic heading. 
Print topic heading 

associated with begi n_l abe 1 . 
Print topic headings from 
begi n_l abe 1 to end_label to 
the maximum depth of the two 
1 abel s . 

Print topic headings from 
begi n_l abel to end_label to 
the depth specified. 

Print current topic heading 
and text. 

Print topic heading and text 
associated with beg i n__l abe 1 . 
Print topic headings and text 
from beg in_l abel to end_label 
to the maximum depth of the 
two labels. 

Print topic headings and text 
from beg in_l abel to end_label 
to the depth specified. 

Print topic headings where 
the ASCII string appears in 
the topic heading or text. 



Call the peruse__text segment 
specified (in a special 
system directory). 

Call the peruse_text segment 
specified by complete 

pathname . 



Return 

segment 

current 

Return 
leve 1 . 



to the 

from 
one was 



peruse_text 
which the 
cal 1 ed. 



to Multics command 
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Name : pll, v2pll 

The pll command invokes the PL/I compiler to translate a 
segment containing the text of a PL/I source program into a 
Mul tics object segment. A listing segment is optionally 
produced. These results are placed in the user's working 
directory. This command cannot be called recursively. 



U sag e 



pll pathname - control __ar gl- 



-cont rol_argji- 



1) pathname 



is the path name of a PL/ I source 
segment that is to be translated by the 
PL/I compiler. If the source segment 
name does not have a suffix of .pll, 
then one is assumed. 



2) control_argi 



-source, -sc 



-symbols, -sb 



can be chosen from the following list of 
control arguments: 

produces a line-numbered printable ASCII 
listing of the program. The default is 
no list i ng. 



lists the source program as 
all the names declared in 
with their attributes. The 
no symbols. 



above and 
the program 
default is 



-map 



-list, -Is 



lists the source program and symbols as 
above, followed by a -map of the object 
code generated by the compilation. The 
-map control argument produces 
sufficient information to allow the user 
to debug most problems on-line. The 
defaul t is no map. 

lists the source programs and symbols 
as for the -symbols control argument, 
followed by an assembl y- 1 i ke listing of 
the compiled object program. Note that 
use of the -list control argument 
significantly increases compilation time 
and should be avoided whenever possible 
by using the -map control argument. The 
def au It is no list. 
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-brief, -bf causes error messages written into the 

stream "er ror_output" contain only an 
error number, statement identification/ 
and, when appropriate/ the identifier or 
constant in error. In the normal/ 
non-brief mode, an explanatory message 
of one or more sentences is also 
wr i tten. 



-sever ityL/ -svi 



-check/ -ck 



-optimize/ -ot 



-table, -tb 



causes error messages whose severity is 
less than i (where 1 is 1, 2, 3, or k; 
e.g./ severity3) to not be written into 
the "error^output" stream although all 
errors are written into the listing. 
The default value for j_ is 1. 

is used for syntactic and semantic 
checking of a PL/ I program. Only the 
first three phases of the compiler are 
executed. Code generation is skipped as 
is the manipulation of the working 
segments used by the code generator. 

invokes an extra compiler phase just 
before code generation to perform 
certain optimizations such as the 
removal of common subexpressions. Use 
of this control argument adds 5-10% to 
the compilation time. 

generates a full symbol table for use by 
symbolic debuggers; the symbol table is 
part of the symbol section of the object 
program and consists of two parts: a 
statement table that gives the 
correspondence between source line 
numbers and object locations/ and an 
identifier table containing information 
about every identifier used by the 
source program. This control argument 
usually causes the object segment to 
become significantly longer. 



brief_table/ -bftb generates a partial symbol table 

consisting of only statement lables for 
use by symbolic debuggers. The table 
appears as the symbol section of the 
object segment produced for the 
compilation. This control argument does 
not significantly increase the size of 
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the object program. 



-profile/ -pf generates additional code to meter the 

execution of individual statements. 
Each statement in the object program 
contains an additional instruction to 
increment an internal counter 
associated with that statement. After a 
program has been executed, the 
pr i nt_prof i le command can be used to 
print the execution counts. See the MPM 
command write-up of the pr i nt_prof i 1 e 
command. 

The following control arguments are available, but are 
probably not of interest to the normal user. 

-debug, -db leaves the list-structured internal 

representation of the source programs 
intact after a compilation. This 
control argument is used for debugging 
the compiler. The command pll$clean_up 
can be used to discard the list 
structure. 

-time, -tm After compilation, this control argument 

prints a table giving the time, in 
seconds, the number of page faults, and 
the amount of free storage used by each 
of the phases of the compiler. This 
information is also available from the 
command pll$times typed after a 
compi 1 at ion. 

Further information on the above control arguments is 
contained under the headings Error Diagnost i cs and Li sting . 

Notes 

A normal compilation produces an object segment, segname, 

and leaves it in the user's working directory. If segname 

existed previously in the directory, its access control list 

(ACL) is saved and given to the new copy of segname. Otherwise, 
the user is given "re" access to the segment with ring brackets 

v,v,v where v is the validation level of the process active when 
the object segment is created. 

The user's control arguments control the absence or presence 
of the listing segment for segname. pll and the contents of that 
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listing. if created, the listing segment is named segname . 1 i st . 
The ACL is as described for the object segment except that the 
user is given "rwa" access to it when newly created. Previous 
copies of segname and (if the list option is on.) segname.list are 
replaced by the new segments created by the compilation. 

Note that because of the Multics standard that restricts the 
length of segment names, a PL/ I source segment name cannot be 
longer than 2k characters. 

Error DiagnQSt ics 

The PL/ I compiler can diagnose and issue messages for about 
350 different errors. These messages are graded in severity as 
fol lows : 

Severity level Meaning 

1 Warning only - compilation continues without ill 
effect . 

2 Correctable error - the compiler remedies the 
situation and continues, probably without ill 
effect. For example, a missing end statement can 
be and is corrected by simulating the appending of 
the string ";end; M to the source to complete the 
program. This does not guarantee the right 
results however. 

3 An uncorrectable but recoverable error. That is, 
the program is definitely in error and cannot be 
corrected but the compiler can and does continue 
executing up to the point just before code is 
generated. Thus, any further errors are 
diagnosed. 

i* An unrecoverable error. The compiler cannot 

continue beyond this error. The message is 
printed and then control is returned to the pll 
command unwinding the compiler. The command 
writes an abort message into the "er ror_output" 
stream and returns to its caller. 

Error messages are written into the stream "er ror_output" as 
they occur. Thus, a user at his terminal can quit his 
compilation process immediately when he sees something is amiss. 
As indicated above, the user can set the severity level so that 
he is not bothered by minor error messages. He can also set the 
-brief control argument so that the message is shorter. An 
example of an error message in its long form is: 
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ERROR 158, SEVERITY 2 ON LINE 30 

A constant immediately follows the identifier "zilch". 
Source: a = zilch k; 

If the -brief control argument had been specified, the user would 
see instead: 

ERROR 158, SEVERITY 2 ON LINE 30 
z i 1 ch 

If the user had set his severity level to 3, he would have 
seen no message at all. 

Once a given error message has been printed on the user's 
terminal in the long form, all further instances of that error 
message use the brief mode. 

If no explanatory text appears with the first instance of a 
info, the user should use the help command to consult 
>documentation>info>pl 1. status. info. This situation arises when 
a new error is defined before the segment containing the message 
text is updated. 

If the -list control argument has been specified, the error 
messages are also written into the listing segment. They appear, 
sorted by line number, after the listing of the source program. 
Because of an implementation restriction, no more than 100 
messages are printed in the listing. 

The pll command issues a warning if any variables have been 
declared by context or implication. This warning does not appear 
in the listing segment. 

Listing 

The listing created by PL/I is a line-numbered image of the 
source segment. This is followed by a table of all of the names 
declared within the program. The names are categorized by 
declaration type which are: 

1) declare statement; 

2) explicit context (labels, entries, and parameters); 

3) implicit context. 

Within these categories, the symbols are sorted 
alphabetically and then listed with their location; storage 
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class; data type; size, precision, or ievei; 
"initial", "array", " i nternal ", "external ", 
"unaligned"; and a cross-reference list. The 
followed by the error messages. 



SLiuii as 

"al i gned" and, 
symbol 1 i st i ng is 



The object code map follows the list of error messages. 
This table gives the starting location in the text segment of the 
instructions generated for statements starting on a given line. 
The table is sorted by ascending storage locations. 

Finally, the listing contains the assembl y- 1 i ke listing of 
the object segment produced. The executable instructions are 
grouped under an identifying header that contains the source 
statement that produced the instruction. Opcode, base-register, 
and modifier mnemonics are printed alongside the octal 
instruction. If the address field of the instruction uses the IC 
(self-relative) modifier, the absolute text location 
corresponding to the relative address is printed on the remarks 
field of the line. If the reference is to a constant, the octal 
value of the first word of the constant is also printed. if the 
address field of the instruction references a symbol declared by 
the user, its name appears in the remarks field of the line. 



Reference 

1) The MULTICS PL/1 Language . A semiformal definition of the 
Multics PL/1 language. 
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Name : pll_abs, pa, v2pll_abs, v2pa 

This command submits an absentee request to perform PL/ I 
compilations using the Version 2 PL/ I compiler. The absentee 
process for which pll_ abs submits a request compiles the segments 
named, appends the output of pr i nt_l i nk_ i nf o for each segment to 
the segment segnamei. 1 i st if it exists, and dprints and deletes 
segnamej.. list. If the -output_file control argument is not 
specified, an output segment, segname.absout/ is created in the 
user's working directory (if more than one segname is specified, 
the first is used). if the segment to be compiled cannot be 
found, no absentee request is submitted. 



Usage 

p 1 l_ab s s egnamel 

1) segnamej. 

2) pll_args 



3) pll_abs_args 



-queue r, -q a 



-copy a/ -cp a 



-hold 



segnamea -pll_args- -pi l_abs_args- 

is the path name of a segment to be 
compiled. 

can be one or more nonobsolete control 
arguments accepted by the PL/ I compiler 
and described in pll. (See the write-up 
in the MPM.) Control arguments must 
begin with a minus sign (-). 



can be one or more 
control arguments: 



of the following 



specifies in which priority queue the 
request is to be placed (a <= 3). The 
default queue is 3. segnamei. 1 i st is 
also dprinted in queue a* 

spcecifies the number of copies (a < = **) 
of segnamej.. 1 i st to be dprinted. The 
default is 1. 

specifies that pll_abs should not dprint 
or delete segnamei. 1 i st . 



■output_fi le JF, -of f. specifies that absentee output is to go 

to segment f. where f is a path name. 
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Notes 

Control arguments and segment names can be mixed freely and 
can appear anywhere on the command line after the command. All 
control arguments apply to all segment names. An unrecognizable 
control argument causes the absentee request not to be submitted. 

Unpredictable results can occur if two absentee requests are 
submitted which could simultaneously attempt to compile the same 
segment or write into the same .absout segment. 

When doing several compilations, it is more efficient to 
give several segment names in one command rather than several 
commands. With one command, only one process is set up. Thus 
the links that need to be snapped when setting up a process and 
when invoking the compiler need be snapped only once. 



(c) Copyright, 1973, Massachusetts Institute of Technology 

and Honeywell information Systems Inc.' (END) 



MULT ICS PROGRAMMERS 1 MANUAL 



print 



Command 
2/20/73 



N ame : print, pr 



The print command prints a specified ASCII segment on the 
user's terminal. Unless the user specifies a range of line 
numbers, the command prints the entire segment. 

Usa,ge 

print path -begin- -end- 



1) path is the path name of the segment to be printed. 

2) begin is the line number from which to begin printing and is 

optional. It it is not specified, printing starts on 
the first line of this segment. If begin is not 
specified, then end may not be specified either. 

3) end is the line number to end printing; it is optional and 

if not specified, printing ends with the last line of 
the segment. 



Notes 



If neither begin nor end is supplied, a short identifying 
header will precede the printing of the segment. This header is 
suppressed whenever begin is nonnull. See Exampl es below. 

The command assumes that "new 1 ine" characters are 
appropriately embedded in the text. Output is written on the I/O 
output stream "user_output n which is usually directed to the 
user 1 s termi nal . 

The user must have read access to the segment to be printed. 

Exampl es 

print alpha 

prints the segment alpha in the user's working directory in its 
entirety. 



print alpha 1 



has the same effect, but omits the identifying header. 



print alpha 10 20 



prints lines 10 through 20 of the segment. 
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print alpha 10 
prints lines 10 through the end of the segment. 

print alpha 1 10 
prints the first ten lines of the segment. 
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pr i n t_attach_tabl e 



Command 

Standard Service System 

7/28/71 



Name : pr i n t_attach_tabl e, pat 

This command prints on the user's console the I/O stream 
name associations created by attach calls in the user's current 
ring. 

pr i nt_attach_tabl e -s tream_.name.L- ... -st ream_.namejv- 

1) stream_namel is the name of a stream about which 

information is to be printed. 

Notes 

The type and identifying names of the devices associated 
with the indicated stream names will be printed. If no arguments 
are specified, the information for all streams currently attached 
wJ 11 be pr i n ted. 



(END) 
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Name : pr i nt_bi nd_map / pbm 

The pr i nt_bind_map command displays all or parts of the bind 
map of an object segment generated by version number h of the 
binder or subsequent versions. Note: if the object segment was 
bound by the old bindarchive command or by earlier versions of 
the binder, it will ask the user to print the appropriate map 
segment. 

Usage 

print_bind_map path -comp_l- ... -compn- -control_args- 
1) path is the path name of a bound object segment. 



2 ) compi 



are the optional names of one or more 
components of this bound object. Only the 
lines corresponding to these components will 
be displayed. A component name must contain 
one or more non-numeric characters. If it is 
purely numerical, it is assumed to be an 
octal offset within the bound segment and the 
line corresponding to the component residing 
at that offset will be displayed. A 
numerical component name may be specified by 
preceding it with the control argument 
"-name" ("-nm"). 



3) control_args 
-long, -lg 



may be any of the following: 

in addition to the components 1 relocation 
values (displayed in the default brief mode), 
the command also displays their compilation 
time and their source language. 



-name, -nm 



the following compl argument is the 
numerical name of a component segment. 



purel y 



-no_header 
-nhe 



the command will omit all headers, 
only lines concerning the 
themselves . 



printing 
components 



Note 

If no 
di spl ayed. 



component names are specified, the entire bind map is 
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Command 

Standard Service System 
11/11/70 



Name: pr i n t_da rtmouth_l i bra ry, pdl 

This command prints the pathname of the Multics directory 
being used as the current user library for the Dartmouth 
subsystem. The user 1 ibrary is searched whenever a Dartmouth 
Basic program produces a program name ending in "***". 

Usage 

pr i nt_dartmouth_l ibrary 



(END) 
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Command 

Standard Service System 
02/16/71 



Name : pr i nt_def aul t__wdi r, pdwd 

The pr i nt__def aul t_wdi r command causes the current default 
working directory f s name to be printed at the console. 

Usage 

pr i nt__def au 1 t_wd i r 

Note 

See also change__wdir and change_def au 1 t_wd? r in the MPM. 
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Command 

Standard Service System 

7/28/71 



Name : pr i nt_J i nk_i nf o, pi i 



The pr i nt_l i nk_i nfo command prints selected items of 
information for the specified object segments. 

usage 

pr i nt_l i nk_i nf o pat hi. ... patha option! •' • • option 

1) path! is the pathname of the object segment to be 

di spl ayed. 

2) optionjL is chosen from the following list of options. 

It may appear anywhere on the command line 
and applies to all pathnames. If no option 
is specified/ all of them are assumed by 
default. In this case, information 
describing the segment's actual file system 
location (tree name) and the circumstances of 
its creation (creation time, generator name, 
etc.) is also displayed. 



-length, -In displays the object segment sections' 
lengths . 

-entry, -et is a listing of the object segment's external 
definitions/ giving their symbolic names and 
their relative addresses within the segment. 

-link, -lk is an alphabetically sorted listing of all 
the external symbols referenced by this 
object segment. 
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Command 
Development System 
02/12/71 



Name : pr i nt__l i nkage_usage, plu 

This command prints out all linkage segment usage for a 
process. This information is useful for debugging purposes or 
for analysis of a process 1 use of its linkage segments. 

Every procedure segment and each data segment that has 
definitions has a linkage section associated with it. 

Usage 

print_J i nkage_usage 

Notes 

The information printed for each linkage block is the name 
of the corresponding segment/ the segment number/ the offset/ and 
the length of the linkage block. The printout is in order by the 
segment number and the offset of the linkage block. The command 
prints the position and size of each block within a combined 
linkage segment that is not used for linkage. 
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Name : print_motd, pmotd 

The print__motd command is intended to be used within a 
start_up.ec segment. It prints out changes to the message of the 
day since the last time the command was called. For a 
description of the function of a startup. ec segment see the MPM 
Reference Guide section, Protocol for Logging In. 

Usage 

p r i n t_mo t d 

Mptes 

The current segment >system_control__l>message_of_the_day is 
compared with the segment User.motd (where User is the user's 
name) found in the user's home directory. All newly inserted or 
modified lines are printed on the console/ and the user's copy is 
updated for use the next time print_motd is invoked. 

If the segment User.motd does not exist, print_motd will 
attempt to create it, print the current message of the day, and 
initialize User.motd. 
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Command 
Development System 
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Name : pr i nt_search_rul es, psr 

The pr i n t_search_rul es command causes the printing of the 
currently operating search rules in the user output stream. 

Usa.se 

pr i nt_sea rch_.ru 1 es 

Notes 

See also se t__search_ rul es and set_search_di rector i es in the 

MPM. 



(END) 
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Command 

Standard Service System 
02/11/71 



Name : print__wdir/ pwd 

The print_ wdir command prints out the name of the current 
working directory on the user's console. 

Usage 

pr i n t_wd i r 



(END) 
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Name : profile 

The profile control argument of the pll and fortran commands 
causes the compiler to generate an internal static table 
containing an entry for each statement in the source program; the 
table entry contains information about the source line as well as 
a counter that starts out as zero. Each statement in the program 
is modified to start with an instruction to add one to the 
counter associated with the statement. The profile command 
allows the user to print and reset these counters. 

Usage 

profile namel. ... namea -ctl__arg.l- ... -ctl_argn- 

1) namel is the pathname or reference name of a 

program whose counters are to be printed or 
reset. 

2) ctl_argl is selected from the following list. Control 

arguments apply to all programs whose names 
appear in the command line. 

-print, -pr causes profile to print the following 

information for each statement in the 
specified programs. 

1. 1 ine number 

2. statement number 

3. number of times the. statement has been 
executed. 

k. cost of executing the statement measured 
in number of instructions executed online 
plus the number of jumps into 
pi l__operators__. Note that each 

instruction and each jump into 
pl l_operators_ count as only one unit. 

5. the names of all operators in 
pl l__operators__ used by this statement. 

The total cost for all statements is printed 
at the end. 

-brief, -bf causes profile to omit from the statement 

list statements that have never been 
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-long/ -lg 
-reset, - r s 



execu ted . 

causes profile to include the statement list 
statements that have never been executed. 

causes profile to reset to zero all counters 
in the specified program. 

The default control arguments are -print and 
-brief. 

Example 

The PL/ I program shown below counts the number of 
occurrences of one string in another string. It was compiled 
with the -profile control argument and executed once. The output 
from the profile command/ which is printed below/ shows an 
anomaly of the current implementation — there is only one 
counter for the statement: 



if 



then 



so that one cannot determine the number of times the condition 
was satisfied. 

The source code for the program is: 

example: proc(sl/s2); 

declare (sl/s2) char(*)/ 
(i/k) fixed bin, 
ioa_ options (variable); 

k = 0; 

do t = 1 to length(sl) - 1 ength(s2 ); 

if substr(sl/ i/length(s2)) = s2 then k = k + 1; 
end; 

call ioa_( l, " , d ,, /k); 
end example; 



(c) Copyright/ 1973/ Massachusetts Institute of Technology 
^ and Honey we 1 1 I nf orma t i on Systems I nc. 



MULT ICS PROGRAMMERS' MANUAL 



prof i 1 e 



Page 3 
11/5/73 



After executing the program 
profile command is: 

LINE STM COUNT COST 



7 1 11 

8 1 18 

9 1 27 351 + 
10 1 27 5k 

12 1 1 Ik + 

13 1 1 0 + 

TOTAL k2S + 



once, the output from the 

PROGRAM 
example 

5k (set_cs cp_cs) 

1 (cal l_ext_out__desc) 
1 (return) 

56 
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Command 
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Name ; program_i n terrupt, pi 

The program_i nterrupt command allows the users of editors, 
subsystems and other interactive programs to interrupt those 
programs and re-enter them at known places. 

When the user wants to interrupt a program he presses the 
quit button and types program_i nter rupt or pi after receiving a 
ready message. If the program thus interrupted is not prepared 
to accept the interrupt, the system will print a message of the 
form "no active handler for program_i nter rupt" . Otherwise the 
interrupt is accepted and what happens next depends on the 
particular program that was interrupted. 

Usage, 

program__i nterrupt 

Note 

To make use of the program interrupt facility, a program or 
subsystem must establish a condition handler for the condition 
"program_interrupt". When the user invokes the program_interrupt 
command, the handler established by the program or subsystem is 
invoked. For a discussion of conditions see the MPM Reference 
Guide sections, the Multics Condition Mechanism, and List of 
System Conditions and Default Handlers. 

Example 

The edm command has a handler for the "program_i n terrupt" 
condition which, when it is entered, stops whatever the editor is 
doing and looks for a request from the user's terminal. Thus, a 
user of edm who inadvertantly typed "plOO" (to print 100 lines) 
could kill this printout by pressing the quit button and then 
typing program_interrupt. 



(c) Copyright, 1973, Massachusetts Institute of Technology 

^ and Honeywell Information Systems Inc. (END) 



MULT ICS PROGRAMMERS 1 MANUAL 



progress 



Command 
8/U/73 



Name : progress / pg 

The progress command executes a specified command line and 
prints information about how its execution is progressing in 
terms of CPU time/ real time, and page faults. 

Usage 

progress -cont rol_arg- -command_l i ne- 

1) control_arg if present, progress performs 

only the function specified by 
that control argument. No 
command_line argument can follow 
except in the case of -brief. 
The control argument can be one 
of the fol 1 owi ng : 



-off 



-on 



-brief, -bf 



suppresses the incremental 
messages (see Output Messages 
below) printed during execution 
of a command line previously 
initiated, but does not suppress 
the message printed when that 
command line is finished. This 
control argument can be used to 
suppress messages while 

debuggi ng. 

restores the printing of 
incremental messages during 
execution of the command line. 

permits only the message at 
completion of the command line to 
be printed. The command__l i ne 
argument is used following this 
control argument. 



output_st ream stream_name 
■os strearn_name 



directs output from the progress 
command to be printed on the I/O 
stream, stream_name. The default 
stream is user_i/o. 



-cput a 



causes progress to print its 
incremental message every a 
seconds of virtual CPU time. The 
default is -cput 10. 
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- rea 1 t & causes progress to print its 

incremental message every a 
seconds of real time. The 
default is -cput 10. 

2) command_line is a character string made up by 

concatenating all the arguments 
to progress (excluding the first 
if it is a control argument) with 
blanks between them. The string 
is executed as a command line. 
It can appear as the only 
argument or following the -brief 
control argument. 

Output Messages 

After every 10 seconds of virtual CPU time (assuming the 
default triggering value is used), progress prints out a message 
of the form: 

ct/rt = pt|, ci/ri = pi % (pfi) 

where : 

1) ct is the number of virtual CPU seconds used by the 

command line so far. 

2) rt is the total real seconds used. 

3) pt is the percentage of total real time that the command 

was executing. 

k) ci is the incremental virtual CPU time (since the last 

message) . 

5) ri is the incremental real time. 

6) pi is ci expressed as a percentage of ri. 

7) pfi is the number of page faults per second of virtual CPU 

time (since the last message). 

When the command line finishes, progress prints the 
following message: 

finished: ct/rt = pt% (pft) 

where : 
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8) pft is the number of page faults per second of virtual CPU 
time for the execution of the entire command. 

Example 

progress pi 1 newseg -list 
PL/I 

10/30 = 332, 10/30 = 332 (26) 
20/50 - k0%, 10/20 = 50% (17) 
30/123 = 2k%, 10/73 = 132 (20) 
finished: 33/150 = 222 (22) 
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Name : qedx, qx 

The qedx context editor can be used to create and edit ASCII 
segments in Multics. The editor is based on the QED editor as 
implemented by K. L. Thompson of Bell Telephone Laboratories, 
qedx is basically a subset of QED and is designed to provide the 
user with much of the power of QED and performance similar to the 
simpler edm editor also described in this manual. 



Usage 



qedx -inst_path- -a rgl- ... -argiv 



1. inst_path is an optional argument and, if present, 

specifies the pathname of an ASCII segment 
from which the editor is to take its initial 
instructions. Such a set of instructions is 
commonly referred to as a macro. The editor 
automatically concatenates the suffix ".qedx" 
to inst__path to obtain the complete pathname 
of the segment containing the qedx 
i nstruct ions. 



2. argj_ is an optional argument that is appended as a 

separate line to the buffer "args"; argl 
becomes the first line in the buffer, and 
argn becomes the last. Arguments are used in 
conjunction with a macro specified by 
instr_path. See I ni tal ization o_f Macros 
bel ow. 



If inst_path is provided, the editor executes the qedx 
requests contained in the specified segment and then interrogates 
the user's terminal for further requests. If inst__path is 
omitted, the editor immediatesly interrogates the user's terminal 
for the first qedx request. The use of the inst__path argument 
requires a fairly detailed understanding of the editor and 
further discussion of this feature is delayed until later in this 
v/rite-up. For the moment, we will restrict our discussion to the 
most straightforward use of the editor. 

Once the qedx command is invoked, the user can immediately 
begin to issue qedx requests from his terminal. Requests fall 
into one of two general categories, input requests and edit 
requests. Input requests place the editor into input mode, which 
allows the user to enter new ASCII text from his terminal until 
an appropriate escape sequence is typed to switch the editor back 
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to edit mode. Edit requests allow the user to read and write 
ASCII segments and perform various editing functions on ASCII 
data. Input and editing operations are not performed directly on 
the target segments but in a temporary workspace known as a 

buffer. 

To create a new ASCII segment, a user might perform the 
fol lowi ng steps . 

1. Invoke qedx and enter input mode by typing one of the input 
requests (e.g., append) as the first qedx request. 

la) Enter ASCII text lines into the buffer from the 
termi nal . 

lb) Leave input mode by typing the appropriate escape 
sequence as the first characters of a new line. 

2. Inspect the contents of the buffer and make any necessary 
corrections using edit or input requests. 

3. Write the contents of the buffer into a new segment using 
the write request and exit from the editor using the quit 
request . 

To edit an existing ASCII segment, a user might perform the 
fol lowing steps. 

1. Invoke qedx and read the segment into the buffer by giving a 
read request as the first qedx request. 

2. Edit the contents of the buffer using edit and input 
requests as necessary. 

3. Using the write request, write the contents of the modified 
buffer either back into the original segment or, perhaps, 
into a segment of a different name and exit from the editor. 

The user can create and edit any number of segments with a 
single invocation of the editor as long as the contents of the 
buffer are deleted before work is started on each new segment. 

5di tor Requests 

In the list given below, editor requests are divided into 
three categories: input requests, basic edit requests, and 
extended edit requests. The basic edit requests are sufficient 
to allow a user to create and edit ASCII segments and provide a 
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functional capability quite similar to edm. The extended 
requests are, in general/ a little more difficult to learn to use 
and the discussion of these requests is postponed until later in 
this write-up. Note that the letter given in parentheses is the 
actual character used to invoke the request in qedx and does not 
always bear a relation to the name of the request. 



1. Input Requests 
append (a) 

change (c) 

i nsert ( i ) 



Enter input mode, append 1 ines typed from the 
terminal after a specified line. 

Enter input mode, replace the specified line 
or lines with lines typed from the terminal. 

Enter input mode, insert lines typed from the 
terminal before a specified line. 



2. Basic Edi t Requests 



delete (d) 

print (p) 

quit (q) 
read (r) 
substitute (s) 

write (w) 



Delete specified line or lines from the 
buffer . 



Print specified line or 
termi nal . 



1 i nes on 



the 



Exit from the editor. 

Read specified segment into the buffer. 

Replace specific character strings 
specified line or lines. 



i n 



Write current buffer into specified segment. 



3. Extended Edi t Requests 



execute (e) 

1 i ne number ( = ) 
global (g) 



Pass remainder of request line to the Multics 
command processor (i.e., escape to other 
commands ) . 

Print line number of specified line. 

Print, delete or print line number of all 
addressed lines that contain a specified 
character string. 
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exclude (v) 
buffer (b) 

move (m) 
status (x) 
Addressing 



Print, delete or print line number of all 
addressed lines that do not contain a 
specified character string. 

Switch to specified buffer (i.e./ change base 
of all subsequent editor operations to 
specified buffer). 

Move specified line or lines into a specified 
aux i 1 i ary buffer. 

Print on the terminal a summary of the status 
of all buffers currently in use. 



The qedx editor is basically a line-oriented editor in that 
editing requests usually operate on an integral number of ASCII 
lines. As a result, most editing requests are preceded with an 
address specifying the line or lines in the buffer on which the 
request is to operate. There are three basic means by which 
lines in the buffer can be addressed: 



1. Addressing by line number; 



2. Addressing relative to the "current" line; 



3. Addressing by context. 



In addition, a line address can be formed using a combination of 
the above techniques. 

1. Addressing. by_ line. Number 

Each line in the buffer can be addressed by a decimal number 
indicating the current position of the line within the buffer. 
The first line in the buffer is line 1, the second line 2, etc. 
The last line in the buffer can be addressed either by line 
number or by using the $ character, which is interpreted to mean 
"the last line currently in the buffer". In certain cases it is 
possible to address the (fictitious) line preceding line 1 in the 
buffer by addressing line 0. 

As lines are added to or deleted from the buffer, the line 
numbers of all lines that follow the added or deleted lines are 
relocated accordingly. For example, if line 15 is deleted from 
the buffer, line 16 becomes line 15, 17 becomes 16, and so on. 
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If an attempt is made to address a line not contained in the 
buffer, an error message is printed by the editor. If the buffer 
is currently empty, as it is when the editor is first entered, 
only the line numbers 0 and $ are considered valid. 

2. Addressing Relative Jta £he_ Current Line 

The qedx editor maintains the notion of a "current" line 
that is addressable by using the character "." (period) to 
represent the address of the current line. Normally, the current 
line is the last line addressed by an edit request or the last 
1 ine entered from the terminal by an input request. The value of 
"." after each editor request is documented in the description of 
the request. 

Lines can be addressed relative to the current line number 
by using an address consisting of "." followed by a signed 
decimal number specifying the position of the desired line 
relative to the current line. For example, the address .+1 
specifies the line immediately following the current line and the 
address .-1 specifies the line immediately preceding the current 
1 i ne. 

When specifying an increment to the current line number, the 
+ sign can be omitted (e.g., .5 is interpreted as .+5.. In 
addition, when specifying a decrement to the current line number, 
the "." itself can be omitted (e.g., -3 is interpreted as .-3.. 
It is also possible to follow "." with a series of signed decimal 
numbers (e.g., .5+5-3 is interpreted as .+7). 

3. Addressing by. Context 

Lines can be addressed by context by using a regular 
expression to match a string of characters on a line. When used 
as an address, a regular expression specifies the first line 
encountered that contains a string of characters that matches the 
regular expression. In its simplest form, a regular expression 
used as an address performs in a manner similar to the edm locate 
(1) request. For example, in the following text, the regular 
expression /abc/ matches line 2. 



a : 



procedure; 
abc=def ; 
x=y; 
end a; 
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To use a regular expression as an address, the user types 
/regexp/, where regexp is any valid regular expression as 
described below. The search for a regular expression begins on 
the line following the current line (i.e., .+1. and continues 
through the entire buffer, if necessary, until it again reaches 
the current line. In other words, the search proceeds from .+1 
to $ and then from line 1 to the current line. If the search is 
successful, /regexp/ specifies the first line encountered during 
the search in which a match was found. 

A regular expression can consist of any character in the 
ASCII set except the new line character. However, the following 
characters have specialized meanings in regular expressions. 



Delimits a regular expression used as an address. 

Signifies "any number (or none) of the preceding 
character" . 



When used as the first character of a regular 
expression, the "* character signifies the character 
preceding the first character on a line. 



$ When used as the last character of a regular 
expression, the $ character signifies the character 
following the last character on a line. 



Matches any character on a line. 



Some examples follow: 
/a/ 

/abc/ 

/ab*c/ 

/in. .to/ 

/in.*to/ 

/^abc/ 



Matches the letter "a" anywhere on a 
1 ine. 

Matches the string "abc" anywhere on a 
1 i ne . 

Matches "ac", "abc", "abbe", "abbbc", 
etc. anywhere on a line. 

Matches a line containing "in" followed 
by any two characters followed by "to". 

Matches a line containing "in" and "to" 
in that order. 

Matches a line beginning with "abc". 
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/abc$/ 

/" , abc.*def$/ 
/.*/ 



Matches a line ending with "abc". 

Matches a line beginning with "abc" and 
ending with "def". 



Matches any 1 i ne. 

Matches an empty 
character only). 



1 i ne (new 1 i ne 



The special meanings of "/", "* 



It /It Mo.ll tl£tt II— ill 
/ V / 



and "." within a 



regular expression can be removed by preceding the special 
character wi th £c. 



Matches the string "/*" 
1 ine. 



anywhere on a 



The editor remembers the last regular expression used in any 
context. The user can reinvoke the last used regular expression 
by using a null regular expression (e.g., //). In addition, a 
regular expression can be followed by a signed decimal integer in 
the same manner as when addressing relative to the current line 
number. For example, the addresses /abc/+5-3, /abc/+2 or /abc/2 
all address the second line following a line containing "abc". 



Note that the two 
as special characters in 
by context. 



uses of "." and "$" (as line numbers and 
regular expressions) are distinguished 



4. compound Addresses 

An address can be formed using a combination of the 
techniques described above. The following rules are intended as 
a general guide in the formation of these compound addresses. 

1. If a line number is to appear in an address, it must be 
the first component of the address. 

2. A line number can be followed by a regular expression. 
This construct is used to begin the regular expression 
search after a specific line number. For example, the 
address 10/abc/ starts the search for /abc/ immediately 
after line 10. 
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i cgu i ai 



c nar ! "F ! o rl 



relative to the current line number, 
address .-8/abc/ starts the search 
preceding the current line. 



For example/ the 
from 8 1 ines 



k. A regular expression can be followed by another regular 
expression. For example, the address /abc//def/ matches 
the first line containing "def" appearing after the 
first line containing "abc". As mentioned earlier, a 
regular expression can be followed by a decimal integer. 
For example, the address /abc/-10/def / . 5 starts the 
search for /def/ from 10 lines preceding the first line 
to match /abc/ and if /def/ is matched, the value of the 
compound address is the fifth line following the line 
containing the match for /def/. 

5. Addressing a Series of Lines 



Several of 
ser i es of 1 i nes i 
addresses must be 

A1,A2 



the editor requests can be used to operate on a 
in the buffer. To specify a series of lines, two 
given in the following general form: 



The pair of addresses specifies the series of lines starting with 
the line addressed by the address Al through the line addressed 
by A2 inclusive. 



Exampl es 
1,5 
1/$ 

. 1, /abc/ 



specifies line 1 through line 5. 

specifies the entire contents of the buffer. 

specifies the line following the current line 
through the first line after the current line 
containing "abc". 



When a comma is used to separate addresses, the address 
computation of the second address is unaffected by the 
computation of the first address (i.e., the value of 



ii ii 



changed by the 
the address pa i r 

.1, .2 



i s not 

evaluation of the first address). For example, 



specifies a series of two lines, the line immediately after the 
current line through the second line after the current line. 
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However/ if a semicolon is used to separate addresses 
instead of a comma, the value of "." is set to point to the line 
addressed by Al before the evaluation of A2 begins. In contrast 
to the example given immediately above, the address pair 

.1;.2 

specifies a series of three lines, the line immediately following 
the original current line through the second line following the 
line specified by Al. As a further example, the address pair 

/abc/;.+10 
is equivalent to the address pair 

/abc/,/abc/+10 

6 - Addressing Errors 

The following list describes the various errors that can 
occur when the editor is attempting to evaluate an address. 

1. "Buffer empty" - An attempt has been made to reference 
a specific line when the buffer is empty. (Only "$", 
"." and "0" are legal addresses within an empty buffer 
and only if used with a read, append, or insert 
request. ) 

2. "Address out of buffer" - An attempt has been made to 
refer to a nonexistent line (e.g., an address of 20 
when there are fewer than 20 lines in the buffer or an 
address of .+5 when the current line is fewer than 5 
lines from the last line in the buffer). 

3. "Address wrap around" - An attempt has been made to 
address a series of lines in which the line number of 
the second line addressed is less than the line number 
of the first (e.g., $,1). 

k. "Search failed" - A regular expression search initiated 
from the user's terminal has failed to find a match. 

5. "Syntax error in regular expression" - A regular 
expression used as an address has not been properly 
del imi ted. 
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6* "// unds'f i ned" — A null regular expression has bssn 
used and no previously typed regular expression is 
ava liable. 

Use. of. Ihg. Edi tor 

1. Edi tor Request Format 

A request to the editor can take any one of the following 
three forms depending on the number of addresses to be specified 
with the request. 

1. <request> 

2. ADR<request> 

3. ADR1,ADR2< request) or ADR1; ADR2< request > 

ADR, ADR1, and ADR2 are any legal addresses as specified above, 
and <request> is any valid editor request. 

Some editor requests require no address, some require a 
single address and others require a pair of addresses. In all 
cases, however, the user can use a request omitting one or both 
of the required addresses and let the editor provide the missing 
address information by default. The following general rules 
apply to the use of addresses specified by default. 

1. If a request requiring an address pair is issued with 
the second address missing, the (missing) second address 
is assumed to be the same as the first. For example, 

ADR<request> 

is interpreted as 

ADR, AD R< request > 

and addresses a single line in the buffer (i.e., the 
line addressed by ADR). 

2. If a request requiring an address pair is issued with 
both addresses missing, one of the following address 
pairs is assumed depending on the request issued. 

.,.<request> for most editor requests 

l,$<request> for write, global and exclude 
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3. If a request requiring a single address is issued with 
no address specified, one of the following addresses is 
assumed depending on the request issued. 

.<request> for most editor requests 

$<request> for read requests 

2. The Value of ^ 4 

All editor requests that alter the contents of the buffer or 
cause information to be output on the user's terminal change the 
value of'"." (i.e./ the current line). Usually, the value of "." 
is set to the last address specified (either explicitly or by 
default) in the editor request. The one major exception to this 
rule is the delete request, which sets "." to the line after the 
last 1 ine deleted. 

3. Mul t iple Requests on a_ Line 

In general, any number of editor requests can be issued in a 
single input line. However, each of the requests listed below 
must be terminated with a new line character, and, thus, each 
must appear on a line by itself or at the end of a line 
containing multiple editor requests. 

read (r) 

write (w) 

quit (q) 

execute (e) 

k. Spacing 

The following rules govern the use of spaces in editor 
requests. 

1. Spaces are taken as literal text when appearing inside 
of regular expressions. Thus, /the n/ is not the same 
as /then/. 

2. Spaces cannot appear in numbers, i.e., 13 cannot be 
written as 1 3 (which is interpreted as 1+3 or k.. 

3. Spaces within addresses except as indicated above are 
ignored. 
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h. The treatment of spaces In the body of an editor request 
depends on the nature of the request. 

5. Comments 

The quotation mark character is reserved as the comment 
delimiter and is actually implemented as an editor request, the 
effect of v/hich is to ignore the remainder of the request line. 
If the quotation mark is preceded by an address, the value of "." 
is set to that address. 

6. The Locate Request 

If an address is followed by a new line character, the value 
of "." is set to the addressed line and the line is printed on 
the user's terminal. For example, the request line 

/""start/ 

locates a line beginning with "start", sets the value of "." and 
pr i nts the 1 i ne. 

.7. Responses from Xh& Edj tor 

In general, the editor does not respond with output on the 
terminal unless explicitly requested to do so (e.g., with a print 
or print line number request). The editor does not comment when 
the user enters or exits from the editor or changes to and from 
input and edit modes. The use of frequent print requests is 
recommended for users using the qedx editor for the first time. 

If the user inadvertently requests a large amount of 
terminal output from the editor and wishes to abort the output 
without abandoning the edit, he can hit the quit button on his 
terminal, and, after the quit response, he can re-enter the 
editor by invoking the program_i nterrupt (pi) command. This 
action causes the editor to abandon its printout, but leaves the 
value of "." as if the printout had gone to completion. 

If an error is encountered by the editor, an error message 
is printed on the user's terminal and any editor requests already 
input (i.e., read ahead from the terminal) are discarded. 

If a user exits from qedx by hitting the quit button, and 
subsequently invokes qedx in the same process, the message "qedx: 
Pending work in previous invocation will be lost if you proceed; 
do you wish to proceed?" is printed on the terminal. The user 
must type a "yes" or "no" answer. 
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8. I nput Mode 



The editor can be placed in input mode with the use of one 
of the three input requests (append, change and insert). The 
input request must immediately be followed by a blank or a new 
line character, which in turn is followed by the literal text to 
be input to the buffer. The literal text can contain any number 
of ASCII lines. To exit from input mode and terminate the input 
request, the escape sequence £f is typed, usually as the first 
character of a new line. The £f escape sequence can be followed 
immediately with more editor requests on the same line. The 
usual form of an input request is as follows: 

ADR1(,ADR2. < input request> 

TEXT 

... 

cf 

It is important to remember to terminate the input request 
with the £f before typing another request. Otherwise, the (would 
be) editor request is regarded as input and included in the text 
rather than executed as a request. 

Upon leaving input mode, the value of "." is set to point at 
the last line input from the terminal. 

The special meaning of any of the escape sequences used by 
qedx (e.g., £f , £c, £b, £r) can be suppressed by preceding the 
escape sequence with £c thus allowing these escape sequences to 
be input as literal text. 

I nout Requests 

1. Append (a ) 

The append request is used to enter input lines from the 
terminal, appending these lines after the line addressed by the 
append request. The append request is one of the few requests 
that can operate correctly when the buffer is empty. 

Format: ADRa 

TEXT 
*f 

Default: a is taken to mean .a 



(c) Copyright, 1973, Massachusetts Institute of Technology 

and Honeywell Information Systems Inc. 




Page Ik 



MULT ICS PROGRAMMERS 1 MANUAL 



Value of "." 
Example : 



Set to last 1 ine appended. 
Before 



a: procedure; 
x=y; 
end a; 

Request Sequence 



2a 

Q=r; 
cf 



or 



/x=/a 
q = r; 



After 



ii ii 



a: procedure; 
x=y; 
-> q=r; 

end a; 



Note: 



2. Change lei 



The request Oa can be used to insert text before 
line 1 of the buffer. 



The change request is used to delete an addressed line or 
set of lines and replace the deleted line(s) with new text 
entered from the terminal. 



Format : 

Defaul t : 
Value of 
Exampl e 



ADRl / ADR2c 

TEXT 

*f 

c is taken to mean . ,.c 

Set to last line entered from terminal. 

Before 

a: procedure; 
x-y; 
q=r; 
end a; 
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Request Sequence 



2,3c 
s = t; 
u=v; 
w=z; 



or 



/x=/,/q=/c 
s = t; 
u=v; 
w=z ; 



After 



procedure 
s=t; 
u=v; 
w=z ; 
end a; 



3. Insert ill 



The insert request is used to enter input lines from the 
terminal and insert the new text immediately before the addressed 
line. The insert request is one of the few requests that can 
operate on an empty buffer. 



Format : 

Defaul t : 
Value of 
Example 



ADRi 
TEXT 
*f 

i i s taken to mean . i 

Set to last line inserted. 

Before 

a: procedure; 
x=y; 
end a; 



Request Sequence 



2i 

q=r; 



or 



/x=/i 
q = r; 

<^f 
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A £ +• — 
Ml LCI 

a: procedure; 
M . M -> q=r; 

x-y; 
end a; 

Note: The request ADRi has the same effect as the 

request ADR-la. 

Basic Edi t Requests 

The edit requests described below represent a subset of qedx 
suitable for most editing situations. Additional requests are 
described later in this write-up under extended editor functions. 

1. Delete (d) 

The delete request is used to delete the addressed line or 
set of lines from the buffer. 

Format: ADRI, ADR2d 

Default: d is taken to mean . ,.d 

Value of ".": Set to line immediately following the last line 

deleted. 

Example: Before 

a: procedure; 
x-y; 
q=r; 
s=t; 
end a; 

Request Sequence 

3,Ud or /q=/ / /s=/d 

After 

a: procedure; 
x=y ; 

,, . ,, -> end a; 
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2. Print IjbI 



The print request is used to print the addressed line or set 
of lines on the user f s terminal. 



Format : 
Default: 
Value of 

Example: 



Note: 



3. Quit lal 



ADRl / ADR2p 

p is taken to mean .,.p 

Set to last line addressed by the print request 
(i.e w the last line to be printed). 

Contents of Buffer 

a: procedure; 
x=y; 
q=r; 
s=t ; 
end a; 



Request 

2, Up or 
Console Output 



/x=/, /s=/p 



"."-> 



x=y; 
q=r; 
s=t; 



The output from the print request can be aborted 
with the use of the quit button and 
program_i nterrupt command. 



The quit request is used to exit from the editor and does 
not itself save the results of any editing that might have been 
done. If the user wishes to save the modified contents of the 
buffer/ he must explicitly issue a write request (see below). 



Format : 
Defaul t : 
Special Note: 



The quit request cannot have an address. 

The quit request must be followed immediately by 
a new line character. 
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Read lr± 

The read request is used to append the contents of a 
specified ASCII segment after the addressed line. The read 
request is one of the few requests that operate correctly when 
the buffer is empty. 



Format : 



Default: 
Value of "." 
Exampl e : 



Note 



ADRr PATH 

PATH is the pathname of the ASCII segment to be 
read into the buffer. The pathname can be 
preceded with any number of spaces and must be 
followed immediately by a new line character. 

r PATH is taken to mean $r PATH 

Set to the last line read from the file. 

Before 

a: procedure; 
x=y; 
end a; 

Request 

2r b.pll or /x=/r b.pll 

where b.pll is the following text 

b: procedure; 
c=d; 
end b; 

After 



a: procedure; 

x=y; 
b: procedure; 

c~d * 
"."-> end'b; 

end a; 



The request 
contents of 
buffer. 



Or PATH is used 
a segment before 



to insert the 
1 i ne 1 of the 
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5. Substitute Is! 



The substitute request is used to modify the contents of the 
addressed line or set of lines by replacing all strings that 
match a given regular expression with a specified character 
str i ng. 



Format : 



Defaul t : 

Value of "." 
Operat i on : 



Examples: 



ADRl,ADR2s/REGEXP/ STRING/ 

(The first character after the "s" is taken to be 

the request delimiter and can be any character 

not appearing either in REGEXP or in STRING.) 



s/REGEXP/STRING/ 
.s/REGEXP/STRING/ 



i s 



taken 



to 



mean 



Set to last line addressed by request. 



Each character string in the 
lines that matches REGEXP 
character string STRING. If 

special character &, each 
string matching REGEXP. The 



addressed 1 ine or 
is replaced with the 
STR I NG contains the 
& is replaced by the 
special meaning of & 



can be suppressed by 
escape sequence £c. 



preceding the & with the 



Before: 


The quick brown sox 


Request : 


s/sox/fox/ 


After: 


The quick brown fox 


Before : 


xyz i ndex=q; 


Request : 


s/index/(&)/ 


After: 


xyz ( i ndex )=q; 


Before : 


x=y 


Request : 


s/$/;/ 


After: 


x=y ; 



6. Wr i te (w) 

The write request is used to write 
of lines into a specified segment.' 
already exist, a new segment is created 



the addressed line or set 
If the segment does not 
with the specified name. 
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hormat : 



Def aul t : 
Value of "." 
Exampl e : 



ADRl,ADR2w -PATH- 
PATH is the pathname of the segment the contents 
of which are to be replaced by the addressed 
lines in the buffer. The pathname can be 
preceded by any number of spaces and must be 
followed immediately by a new line character. If 
PATH is omitted, If PATH is omitted and the 
default pathname is null, then the message "No 
pathname given" is printed and qedx awaits 
another request. The default pathname is the 
first pathname used with either a read or write 
request in this invocation of qedx. The default 
pathname is set to null if no pathname has been 
given or if a pathname (either the same one or a 
different one) is used with a read or write 
request a second time. 

w PATH is taken to mean l,$w PATH 

Unchanged 

Request 

2,kvi sam.pl 1 
Resul t 



The second through fourth lines of the 
buffer replace the contents of the segment 
sam.pll in the user's working directory. 

Extended Use of the Edi tor 

The editor requests discussed up to this point comprise a 
basic subset sufficient for most applications. A user learning 
to use qedx for the first time might be well advised to stop at 
this point. 

The editor requests remaining to be described are divided 
into two groups: those that require a knowledge of auxiliary 
buffers and those that do not. Discussion of the former group of 
requests is delayed until the section on auxiliary buffers. 
Discussion of the latter group of requests proceeds below. 
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1. Execute isl 

The execute request is used to invoke the Multics command 
system without exiting from the editor. Whenever an execute 
request is recognized, the remaining characters following the 
execute request in the request line are passed to the Multics 
command processor. The execute request can be followed by any 
legal Multics command line. However, due to a temporary 
restriction, the user should not invoke edm, bsys, or qedx while 
in qedx. 

Format: e <command line> 

Value of " .": Unchanged 

Example: The request line 

e print alpha. pll 

can be used to print a segment in the user's 
working directory. 

The request line 

e list; ma i 1 

lists the user's working directory and prints his 
mailbox (if any). 

Note: If the user wishes to abort a command line issued 

with the execute request, he can hit quit and 
invoke the program_i nter rupt command to abort the 
command line and restore control to qedx. 

2. Print Line Number ( = ) 

There request is used to print the line number of the 
addressed 1 i ne. 

Format: ADR= 

Default: = is taken to mean .= 

Value of ".": Set to line addressed by request 
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OUIILCIIL3 Wl UUI ICI 



a: procedure; 
x=y; 
P=q; 
end a; 



Request 

/q;/ = 
Response 
3 



3. Qlobal 1&1 



The global request is used in conjunction with some other 
request (e.g., print, delete, print line number). That request 
is to operate only on those lines addressed by the global request 
that contain a match for a specified regular expression. 



Format : 



Defaul t : 
Value of 
Note : 

Exampl e : 



ii it 



ADRl,ADR2gX/REGEXP/ 

where X must be one of the following requests 

d delete lines containing REGEXP 

p print lines containing REGEXP 

= print line numbers of lines containing REGEXP 

gX/REGEXP/ is taken to mean 1, $gX/REGEXP/ 

Set to ADR2 of request 

The character immediately following the request X 
is taken to be the regular expression delimiter 
and can be any character not appearing in REGEXP. 

Before 

a: procedure; 
q = r; 
x=y ; 
y=q; 
end a; 
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Request 

l,$gd/q/ 

After 

a: procedure; 
x=y; 

"."-> end a; 

k. Exclude (v) 

The exclude request is also used in conjunction with another 
request (e.g., print, delete, print line number). That request 
is to operate only on those lines addressed by the exclude 
request that do not contain a match for a specified regular 
expression. 



Format : 



Default: 
Value of "." 
Note : 

Exampl e : 



ADRl,ADR2vX/REGEXP/ 

where X must be one of the following requests 

d delete lines not containing REGEXP 
p print lines not containing REGEXP 
= print line numbers of lines not containing 
REGEXP 

vX/REGEXP/ is taken to mean 1, $vX/REGEXP/ 
Set to ADR2 of request 

The character immediately following the request X 
is taken to be the regular expression delimiter 
and can be any character not appearing in REGEXP. 



Before 
a 



procedure; 
q = r; 
x=y; 
y=q; 
end a; 



Request 

l,$v=/q/ 
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Respor ISC 

1 

3 
5 

Aux i 1 iarv Buffers 

The discussion up to this point has assumed the existence of 
only a single buffer. Actually, qedx supports a virtually 
unlimited number of buffers. One buffer at a time can be 
designated as the " current buffer ": any other buffers at this 
time are referred to as aux i 1 i arv buffers . All of the editor 
requests described so far operate within the current buffer. 

Each buffer is given a symbolic name of 1 to 16 ASCII 
characters. When the editor is invoked, a single buffer (buffer 
0) is created by the editor and designated as the current buffer. 
Additional buffers can be created merely by referencing a 
previously undefined buffer name. Each buffer is implemented as 
a separate segment in the user's process directory and, thus, is 
capable of holding any ASCI! segment. 

Buffer names are usually enclosed in parentheses; for 
example, the buffer name Fred is typed as (Fred). However, for 
historical reasons, a buffer name consisting of a single 
character can be typed with or without the enclosing parentheses 
(e.g., "x" is taken to be "(x) M ). 

l. Hie. Change Buffer Request Ihl 

The change buffer request is used to designate an auxiliary 
buffer as the current buffer. The previously designated current 
buffer becomes an auxiliary buffer. 



Format : 



b(X) 



where X is the name of the buffer that is to 
become the current buffer. 



Value of ".": 



Restored to the value of "." when buffer X was 
last used as the current buffer (i.e., the value 
of "." is maintained separately for each buffer 
and saved as part of the buffer status). 
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2. The Move Bequest Ml 



The move request is used to move one or more lines from the 
current buffer to a specified auxiliary buffer. The addressed 
lines replace the previous contents (if any) of the auxiliary 
buffer. 



Format : 



Def aul t : 
Value of "." 

Example: 



ADRl,ADR2m(X) 

where X is the name of the auxiliary buffer to 
which the lines are to be moved. 

m(X) is taken to mean .,.m(X) 

Set to first line after last line moved in 
current buffer. Set to line 0 in the specified 
aux i 1 i ary buffer. 



Before : 
a : 



Request : 
After: 
a : 



Current Buffer 

procedure; 
x=y; 
y=k; 
k=r ; 
end a; 

3,1*01(6) 

Current Buffer 

procedure; 
x=y; 
end a; 



or 



Buffer B 

abc=def ; 
end bin; 



/k;/,/r;/m(B) 

Buffer B 

y=k; 
k=r ; 



3. Ihe_ Buffer Status Request 1x1 



user s 



The buffer status request is used to print on the 
terminal a summary of the status of all buffers currently in use. 
The name and length (in lines) of each buffer is listed; the 
current buffer is specially marked with a right arrow "->" 
immediately to the left of the buffer name. 



Format : 
Value of 



Unchanged 
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Exampl e - 



jf the user has created the additional buffers 
alpha and beta and has designated alpha as his 
current buffer, the output from the buffer status 
request might be as follows. 



157 
32 
53 



(0) 
-Xalpha) 
(beta) 



This output indicates 157 lines in buffer 0 (the 
initial buffer), 32 lines in alpha (the current 
buffer) and 53 lines in beta. 



k. Special Escape Sequences 

The input to qedx can be viewed as a stream of ASCII 
characters. Depending on the context, some of these characters 
are interpreted as editor requests and others are interpreted as 
literal text. The following escape sequences are recognized by 
the editor, in either context, as directives to alter the input 
character stream in some fashion. 

cb(X) This sequence is used to redirect the editor input 



stream to read subsequent input from buffer X. When 
the editor encounters this sequence, the entire escape 
sequence is removed from the input stream and replaced 
with the literal contents of the specified buffer. If 
another £b escape sequence is encountered while 
accepting input from buffer X, the newly encountered 
escape sequence is also replaced by the contents of the 
named buffer. The editor allows the recursive 
replacement of £b escape sequences by the contents of 
named buffers to a recursion depth of 500 nested £b 
escape sequences. 

The buffer to which the input stream is redirected can 
contain editor requests, literal text or both. If the 
editor is executing a request obtained from a buffer 
(rather than from the terminal) and the request 
specifies a regular expression search for which no 
match is found, the usual error comment is suppressed 
and the remaining contents of the buffer are skipped. 
If one thinks of the escape sequence £b(X) as a 
subroutine call statement, the failure to match a 
regular expression specified by some request in buffer 
X can be thought of as a return statement. 
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£r This escape sequence is used to temporarily redirect 

the input stream to read a single line from the user's 
terminal and is normally used when executing editor 
requests contained in a buffer. The £r is removed from 
the input stream and replaced with the next complete 
line entered from the user's terminal. In the line 
that replaces the £r sequence, additional £r or cb 
escape sequences have no effect. 

Note: The special meanings of £b and £r can be suppressed by 

preceding the escape sequence with a £c escape 
sequence. 

5. Use of Buffers for Moving Text 

Perhaps the most common use of buffers in qedx is for moving 
text from one part of a segment to another. A typical pattern is 
to move the text to be moved into an auxiliary buffer with a move 
request. For example, the request 

1, 5m( temp) 

moves line 1 through 5 of the current buffer into the auxiliary 
buffer temp. Once the lines have been moved to an auxiliary 
buffer, they can be used as literal text in conjunction with an 
input request. For example, to insert the lines in buffer temp 
immediately before the last line in the current buffer, the 
following sequence might be used. 

$ i 

£b( tempHf 

In this case, the literal text in buffer temp replaces the £b 
escape sequence and thus is treated as input to the editor 
already placed in input mode by the insert (i) request. Notice 
that the £f immediately following the £b escape sequence is 
correct since it can be expected that the last line in buffer 
temp is terminated by a new line character that precedes the £f 
after the £b(temp) is expanded. 

6. Defining Edi tor CI iches 

Another common use for buffers is for the definition of 
frequently used editing sequences or "cliches". For example, if 
a programmer were faced with the task of adding the same source 
code sequence in several places in a program, he might elect to 
type the editing sequence into a buffer only once and then invoke 
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the contents of the buffer as many times as necessary. In the 
example given below / the contents of buffer new contains the 
necessary editor requests and literal text to append four lines 
of text at any point in the current buffer. 

Example: Contents of buffer new 

a 

if code "=0 then do; 
cal 1 error (code ) ; 
return; 
end; 

Cf 

.lp 

Usage 

ADRcb(new) 

ADR becomes the address of the append request in 
buffer new and specifies the point at which the 
literal text is to be appended. The four lines of 
text in buffer new (lines 2-5. are appended to the 
current buffer, the cf terminates the append 
request and the print request prints the line 
preceding the appended lines, the four appended 
lines and the line following the appended lines. 

7. Use of Edi tor Macros 

The use of buffers in qedx allows a user to place more 
elaborate editor request sequences (commonly called macros) into 
auxiliary buffers and use the editor as a pseudo-programmi ng 
language. In this context, it is useful to regard a buffer 
containing executable editor requests as a subroutine and to view 
the cb escape sequence as a call statement. 

In the example discussed below, a macro is implemented to 
read ASCII text from the terminal until an input terminating 
sequence, a line consisting only of is typed. When the 

terminating sequence is typed, the macro asks the user for a name 
under which the input is filed and exits from the editor. The 
macro is implemented with two executable buffers (subroutines) 
named read and test and is invoked by diverting the input stream 
to the read buffer (i.e., by calling the read subroutine). 
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Example : 



Contents of buffer read 



e ioa_ Type 
$a 

£b(test) 
£b(read) 

Contents of buffer test 



s/^c.$// 



Explanation of the read buffer 

1. The first request in read is an escape to the command 
processor to call ioa_ to print the message "Type 11 on 
the user's terminal. 

2. The second request ($a) places the editor in input 
mode to append text to the end of the current buffer 
(presumably buffer 0). 

3. One line is read from the user's terminal (£r) and the 
append request is terminated (£f). 

h. The contents of buffer test is executed (i.e., read 
"calls" the test "subroutine"). 

5. When and if test "returns", the contents of buffer 
read are executed again (i.e., read "calls" itself). 

Explanation of the test buffer 

1. The first line uses a substitute request to test the 
current line (i.e., the line just read in by the above 
append request) for the input terminating sequence (a 
line consisting only of "."). If the regular 
expression in the substitute request fails to find the 
terminating sequence, the remaining requests in buffer 
test are ignored (i.e., the test subroutine "returns" 
to its caller). 



d 

e ioa 
w £r 
q 



ive me a segment name. 



it 
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9 ! "f f hp f Af-n j pai- I no- connonro ic f r^i in H in cfon 1 . 1~ho 

blank line that previously contained the terminating 
sequence is deleted. 

3. Again ioa_ is used to type a message to the user. 
This time, the macro asks the user for a segment name 
under which the input lines appended by the read 
subroutine are to be stored. 

k. The contents of the current buffer containing the 
input lines are written into a segment, the name of 
which is read from the terminal by the £r escape 
sequence. 

5. The macro exits from the editor with a quit request. 
If the quit request were not included, qedx would 
expect further instructions from the user's terminal 
at this point. 



8. I ni t ial i zat ion of Macros 



The editor provides a means through which a qedx macro can 
be initiated directly from command level. As indicated earlier, 
qedx can be invoked in the following fashion. 



qedx path 



Ihe above command is equivalent to entering the editor with the 
simple command 



qedx 

and immediately executing the following series of requests. 



b(exec) 

r path. qedx 

bO 

£b(exec) 



This request sequence reads the initial macro segment into buffer 
exec, changes the current buffer back to buffer 0 and executes 
the contents of buffer exec. This series of requests is 
sufficient to allow a multi-buffer macro to be initialized. For 
example, the macro given in the previous example can be 
initialized and run from a segment with the following contents. 



b(read)$a 
e ioa_ Type 
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$a 

£c£r£c(!:f 
£ccb(text ) 
£c<j:b( read) 
*f 

b( test)$a 

s/^c<^c.$// 

d 

e ioa_ "Give me a segment name." 

w £e£r 

q 

$f 
bO 

£b(read) 



The contents of the buffers read and test are initialized with 
append requests. Notice that all escape sequences to be placed 
into a buffer as literal text must be preceded by a £c escape 
sequence. Thus, the second line to be input to buffer "read" is 
input as 



£c£r<!:c£f 



to produce the following line in the target buffer. 



tr£f 



In addition to the above, the qedx editor can be invoked 
with more than one argument. Thus, 



qedx read path 



is the equivalent of 



qedx 

b(exec) 

r read. qedx 

b(args) 

a 

path 

*f 
bO 

£b(exec) 
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if the contents of read. qedx is: 
r cb(args) 

then the contents of buffer exec and buffer args become: 

exec ares 

r £b(args) path 

and the request £b(exec) causes the segment with the pathname 
path to be read into buffer 0. At that point the editor waits 
for further commands from the user. 

With the same contents of read. qedx the invocation 

qedx read path l,$s/x/y/ w q 

enters into the buffers exec and args the following: 

exec args 

r £b(args) path 

l,$s/x/y/ 

w 

q 

This causes the editor to read the segment path into buffer 0, 
substitute for every occurence of x the character y, write out 
the segment path and quit, returning to command level. 

Notes 

Since the name of the segment to be read in appears on the 
command line, this feature a 1 1 ows users to use abbreviations (see 
the write-up of the abbrev command) for the names of segments to 
be edited. 

There is no safeguard to keep the editor from changing a 
buffer from which it is also accepting editor requests. If this 
is attempted, havoc may well be the result. 
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Name : ready/ rdy 

The ready command types out an up-to-date ready message 
giving the time of day, the processor time, and the page faults 
since the last ready message was typed. 

Usage 

ready 

Note 

See the MPM commands ready_on and ready_off. 
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Name : ready_off, rdf 

The ready_off command allows the user to turn off, the ready 
message typed on the console after the processing of each command 
line. The automatic typing is suspended until a ready_on command 
is given. 

Usage 

ready_of f 

Note 

See the MPM commands ready and ready., on. 
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Name : ready__on, rdn 

The ready__on command causes the ready message to be 
automatically typed on the console after each command line has 
been processed. The automatic printing is in effect until a 
ready_off command is called. 

Usa^e 

ready_on 

Note 

See the MPM commands ready and ready_off. 
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Name : release, rl 

The release command causes the stack history which was 
preserved by a previous hold command to be released. That is, 
the Multics stack will be returned to a point immediately prior 
to the stack frame of the command which was being executed when 
the quit signal or unclaimed signal which led to the hold command 
occurred . 

Usage 

release -opt- 

1) opt is an optional control argument which if "-all" or 

"-a" causes the stack history preserved by all 
previous hold commands (which have not already been 
released) to be released. 
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Name : rename, rn 

The rename command replaces a specified segment, directory, 
or link name by a specified new name, without affecting any other 
names the entry may have. 

Usage 

rename path.1 namel. . . . pathn namen 

1) pathX specifies the old name which is to be replaced; it 

may be a path name or an entry name. 

2) namel specifies the new name which replaces the storage 

system entry name portion of pathj_. 

Notes 

The star and equals conventions may be used. 

The user's access mode with respect to the directory 
specified by pathl must contain the modify attribute; if the star 
convention is employed, the mode must also contain the status 
attr i bute. 

The entry name namej_ must be unique in the directory 
specified by pathj_; if a name! already exists in the directory, 
the user is interrogated as to whether he wishes the other entry 
which has that name to be deleted. 

Example 

rename alpha beta >sampl e_di r >gamma delta 

causes alpha, -in the user's working directory, to be renamed 
beta, and gamma, in the directory >sample_dir, to be renamed 
del ta. 
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Name : reorder_archi ve 

This command provides a convenient way for ordering the 
contents of an archive segment/ eliminating the need to extract 
the entire contents of an archive and then replace them in the 
order desired. This command will place specified components at 
the beginning of the archive/ leaving any unspecified components 
in their original order at the end of the archive. 



Usage 

reorder_arch i ve -cal.- ... pathl. ... -can" -•• -pathn- 

1) cai may be chosen from the following list: 

-ci if the command is to be driven from console input. 

(This is the default. ) 



-fi if the command is to be driven from a driving list. 

2) pathi is the full path name of the archive segment to be 

reordered; the user need not supply the ".archive" 
suf f i x. 

Notes 



If no control arguments are specified, the default -ci 
(console input) is assumed. 

When the command is invoked with the console input (-ci) 
control argument or with no control arguments, it will type 
"input for arch i ve_name" where arch i ve__name is the name of the 
archive file to be reordered. Component names are then input in 
the order desired, separated by carriage returns. The character 
"." terminates input. The character string ".*" causes the 
command to type back a "*". This feature can be used to make 
sure there are no input errors before typing ".". The character 
string ".q" will cause the command to terminate without 
reordering the archive. 

The driving list (-fi control argument) must have the name 
"name. order" where "name . arch i ve" is the name of the archive 
segment to be reordered. The order segment must be in the 
working directory. It consists of a list of component names in 

the order desired, separated by carriage returns. No "." is 
necessary to terminate the list. Any errors in the list (name 
not found in the archive file, name duplication) will cause the 
command to terminate without altering the archive. 
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The procedure creates a temporary segment named 
!! ra__temp_. arch i ve" in the user's process directory. This 
temporary segment is created once per process, and is truncated 
after it is copied into the directory specified by pathj.. If the 
command cannot copy the temporary segment, it will attempt to 
save it and rename it to the name of the archive specified. 
There is an interval of time, while the command is copying the 
reordered archive into the user's directory, when a quit, not 
followed by a start, will result in the loss of the archive. 
Therefore, quits should be used judiciously. 

The reorder__arch i ve command will not operate upon archive 
segments containing more than 1000 components. 
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Name : repr i nt_er ror , re 

This command allows the reprinting of an error message 
produced by a fault and saved by a "hold" request. The mode of 
the error message may be specified. 

Usage 

repr i nt_error -options- 

1) options may be in any order and are chosen from 

the following list of options: 

-depth _L, -dh X indicates which instance of saved fault 

information is to be used for the 
message (the most recent instance is 
depth 1). This option may appear only 
once per command line. 

-all/ -a prints messages corresponding to all 

existing sets of fault information. 

-brief, -bf prints the short form of the message. 

-long/ -lg prints the long form of the message. 

Notes 

The default form of the message is the normal mode and the 
default depth is 1. 

The message mode options for this command have no effect on 
the operation of the default error handler as such. 

Examples 

The following example illustrates some ways the 
repr i nt_er ror command might be used. 

s i mf 

Error while executing in ring 0: 

Improper access by f i nd_command_$f i nd_command_J 51h 
( >system_l i brary_l>bound_command_l oop_) 
ref erenc i ng >udd>m>Smi th>dw>s i mf | 2 02 
(offset is relative to base of segment) 
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setacl s i mf re 
s i mf 

Error: Attempt by >udd>m>Smi th>dw>s i mf j 20 
to reference through null pointer 

hold 

deh_test l$gate_error 

Error: Gate error by >udd>m>Smi th>dw>deh_tes tl$gate_er ror | 32 0 

referenci ng >system_l i brary_l>hcs__$ i n i t i ate 

Number of arguments expected = 7; number supplied - 3. 

hold 

repr i nt_er ror -all -brief 
level 1 

Error: gate_error 
level 2 
Er ror : 
level 3 

Error: accessv i ola t i on while in ring 0 



simfault 000001 



repr i nt_er ror -long -depth 3 
level 3: 

Error while executing in ring 0: 

Improper access by >system_l i brary_l >bound_sss_act i ve I ii3 
(offset is relative to base of segment) 
referencing >udd>m>Smi th>dw>simf | 202 

The entry into ring 0 was by 

f i nd_command_$f i nd_command_| 51k 

( >system_l i brary__l>bound_command_l oop__| 1U076 ) 

referenci ng >system_l i brary_l>hcs_$make_ptr 

(accessviolation condition) 

repr i nt_er ror 
level 1: 

Error: Gate error by >udd>rn>Smi th>dw>deh_tes t l$ga te_er ror | 32 0 

referenci ng >system_l i brary_l>hcs_$ i n i tiate 

Number of arguments expected = 7; number supplied = 3. 
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Command 
U/27/73 



Name ; resource_usage, ru 



The resource_usage command enables the user to print a 

month-to-date report of his resource consumption, It is not 

possible for a user to use this command to obtain information 
about other users 1 resource usage. 



Usage 



resource_usage -control_arg 



1) control__arg provides the optional feature of selecting 

variable portions of available resource usage 
information. The valid control arguments 
fol low: 



-total, -tt prints only total dollar figures including 

the user's dollar limit stop and his 
month-to-date spending (see Notes below). 

-brief, -bf prints the information selected by the -total 

control argument, and as well precedes this 
information with a header and follows it by 
total dollar figures depicting the user's 
interactive, absentee, and I/O daemon usage. 

-long, -lg prints the most comprehensive picture of the 

user's resource usage. This display includes 
the information selected by the -brief 
control argument and includes an expanded 
report of interactive, absentee, and I/O 
daemon usage which breaks down the total 
dollar charges according to shift and queue, 
breaks down the charged virtual cpu time and 
terminal connect time into hours, minutes, 
and seconds, and displays the charged memory 
units and terminal I/O operations, both 
expressed in thousands. (See Exampl e below.) 



If no control argument is specified, the default action 
results in the selection of slightly less extensive resource 
usage information than that which is printed by the -long control 
argument; namely, all dollar charges are printed but resource 
usage expressed as time is not printed. 
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Notes 

The system calculates a user's month- to-date dollar charges 
when it creates his process. If a user wishes the most 
up-to-date figures, he should issue the new_proc command prior to 
typing resource_usage . 

Notice that in a given usage report, shift and queue numbers 
may not appear in consecutive order as only shifts or queues with 
accrued charges will be listed. 

If no dollar limit stop has been set by a user's project 
administrator, the resource usage report will indicate this by 
the printing of "open" as the dollar limit entry. 



(c) Copyright, 1973, Massachusetts 
^ and Honeywell 
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resource_usage -long 

Doe. Example Report from 04/01/73 1014.7 to 04/10/73 1345.8 

Month-To-Date Charge: $ 292.61; 
Resource Limit: $ 1000.00; 

Interactive Usage: $ 254.31; 19 logins, 7 crashes. 



shift $charge 

1 173.91 

2 54.30 
4 26.10 

Absentee Usage: 

queue $charge 

1 8.74 

3 10.23 



$1 imi t 
open 
open 
open 

$ 18.97; 

jobs 
1 
1 



10 Daemon Usage: $ 19.32; 

queue $charge pieces 
3 19.32 10 



cpu 
0:14:32 
0:05:26 
0:04: 13 



cpu 
0:00:49 
0:00:49 



cpu 
0:01:06 



connect 
14:59:17 
4:52:47 
5:25:18 



memory*K 
.4 
.6 



1 i nes/K 
12 



termi nal 
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Development System 
8/15/72 



Name : runoff, rf 

The runoff command is used to type out text segments in 
manuscript form. Output lines are built from the left margin by 
adding text words until no more words will fit on the line; the 
line is then justified by inserting extra blanks to make an even 
right margin. Up to twenty lines of header and footer can be 
printed on each page. The pages can be numbered, lines can be 
centered, and equations can be formatted. Space can be allowed 
for diagrams. Detailed control over margins, spacing, headers, 
justification, numbering, and other aspects of format is provided 
by control lines beginning with a period interspersed within the 
text, but not appearing in the output segment. The output can be 
printed page by page to allow positioning of paper, or it can be 
directed into a segment. Characters not available on the device 
to which output is directed are replaced by blanks. If special 
symbols must later be hand drawn, a separate segment can be 
created which contains reminders as to where each symbol should 
be placed. The user may define variables and cause expressions 
to be evaluated; in combination with the ability to refer to 
(and sometimes modify) variables connected with the workings of 
the runoff command, the user has extensive control over the 
processing of his text. 

Usage 

runoff pathnamel ... pathnamen. -con t ro l_args- 

1) pathname! is the pathname of an input segment or 

mul t i -segment file (MSF) named entryname . runoff ; 
however, the .runoff suffix may be supplied in 
the entryname. If more than one pathname is 
specified, they are treated as if runoff had been 
invoked separately for each one. The segments 
are printed in the order in which they occur in 
the invocation of the command. 

2) control__args may be chosen from the following list. Any 

control argument specified anywhere in the 
command invocation applies to all segments, and 
control arguments may be intermixed arbitrarily 
with segment names. Control arguments must be 
preceded by a minus sign. 
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-ball jn, ~bl H Output Is converted to a form suitable for an 

jl typeball on a unit equipped with a 
Se 1 ect r i c (R) typ i ng element. Acceptable ball 
numbers are Qkl, 012, 015, and 963. The 
default is the form of the terminal device 
being used. Use of this control argument 
overrides any specification set by the 
-device control argument (below). 

-character, -ch When this control argument is used, certain 

key characters in the output will by flagged 
by putting the line containing the key 
character in a segment named entryname. chars. 
The normal output is not affected. Page and 
line numbers referring to the normal output 
will appear with each flagged line, and 
reminder characters, enclosed by color-shift 
characters, will be substituted for the key 
characters. The default set of key and 
reminder characters corresponds to those 
unavailable with a 963 typeball, as follows: 



left square bracket < 

right square bracket > 

left brace ( 

right brace ) 

tilde t 

grave accent 1 



The key and reminder characters may be 
changed by use of the .ch control line; 
specifying a blank reminder character removes 
the associated key character from the set of 
key characters. If a key character would 
print normally in the output, it should also 
appear in a .tr control line to turn it into 
a blank in the output. 



device n, -dv n. Output is prepared compatible with the device 

specified. This is usually used when the 
output is stored in a segment to be printed 
elsewhere. Suitable devices are consoles 
2741, 1050, 37, and the bulk output printers, 
202 or 300. Use of this control argument 

overrides any specification set by use of the 
-ball control argument; if both are used in 
one invocation of runoff, the last one 
encountered will prevail. 
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If neither -device nor -ball was specified, 
the default device type is that from which 
the user is logged in; any unrecognized type 
is assumed to support the entire ASCII 
character set. 

-from n., -fm n Printing starts at the page numbered ru If 

the -page control argument is used, printing 
starts at the renumbered page jq. 

-hyphenate, -hph When this control argument is used, a 

procedure named hyphenate__word_, which the 
user supplies, will be invoked to perform 
hyphenation when the next word to be output 
will not fit in the space remaining in a line 
(see Hvphenat ion Procedure Cal 1 i ng Sequence 
near the end of this document). Otherwise, 
no attempt will be made to hyphenate words. 

-indent n., -in n. When this control argument is used, the 

output will be indented n spaces from the 
left margin (default indentation is 0 except 
for "-device 202" (the default for -segment), 
which is 20; see also -number below). This 
space is in addition to whatever indentation 
is established by use of the .in control 
word . 

-no_pagi nat ion, -npgn 

Page breaks in the output are suppressed. 

Source line numbers will be printed in the 
left margin of the output; minimum 
indentation of 10 is forced. 

This control argument changes the initial 
page number to n.. All subsequent pages are 
similarly renumbered. Note that if the 
control word .pa is used within the segment 
the -page control argument is overridden and 
the page is numbered according to the .pa 
control 1 i ne . 

pm arg 

The argument arg is assigned as a string to 
the internal variable "Parameter". 



number, -nb 



Page a, -pg n 



-parameter arg , - 
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-pass n. The source segments will be processed n. times 

to permit proper evaluation of expressions 
containing symbols which are defined at a 
subsequent point in the input. No output is 
produced until the last pass. 

-segment/ -sm When this control argument is used, the 

output will be directed to the segment or MSF 
entryname . runout. This control argument 
assumes by default that the material is to be 
dprinted, so the segment is prepared 
compatible with device 202 unless another 
device is specified; thus, unless overridden 
by the -indent control argument, each printed 
line in the output segment is preceded by 20 
leading spaces so that the text will be 
approximately centered on the page when 
dpr i nted . 

-stop, -sp The runoff command will wait for a carriage 

return from the user before beginning typing 
and after each page of output. 

-to n. Printing ends after the page numbered n. 

-wait, -wt The runoff command will wait for a carriage 

return from the user before starting output, 
but not between pages. 



Notes 



A runoff input segment contains two types of lines: control 
lines and text lines. A control line begins with a period; all 
other lines are considered text lines. A two-character control 
word appears in the second and third character positions of each 
control line. The control word may take a parameter which is 
separated from the control word by one or more spaces. Lines 
which are entirely blank are treated as if they contained a 
". sp 1" control 1 i ne. 

Text lines contain the material to be printed. If an input 
line is too short or too long to fill an output line, material is 
taken from or deferred to the next text line. A line beginning 
with a space is interpreted as a break in the text (e.g. the 
beginning of a new paragraph) and the previous line is printed as 
i s . 

Tab characters (ASCII HT) encountered in the input stream 
are converted to the number of spaces required to get to the next 
tab position (11, 21, ...). 
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When an input text line ends with any of the characters 
"?", "!", or or with "?", or "!" followed by a 

double quote or ")", two blanks will precede the following word 
(if it is placed on the same output line), instead of the normal 
single blank. 

The maximum number of characters per input or output line is 
361; this permits 120 underlined characters plus the NL 
character. 

Termi noloev 

Two separate concepts are relevant to understanding how 
runoff formats output: fill mode and ad i us t mode. In fill mode, 
text is moved from line to line when the input either exceeds or 
cannot fill an output line. Adjust mode right justifies the text 
by inserting extra spaces in the output line, with successive 
lines being padded alternately from the right and from the left. 
Note that initial spaces on a line are not subject to adjustment. 
Fill mode can be used without adjust, but in order for adjust to 
work, fill mode must be in effect. 

The 1 i ne 1 ength is the maximum number of print positions in 
an output line, including all spaces and indentations, but not 
including margins set or implied by the -device, -indent, or 
-number control arguments. 

A break insures that the text that follows will not be run 
together with the text before the break. The previous line is 
printed out as is, without padding. 

Vertical spacing within the body of the text is controlled 
by the three commands .ss, .ds, and .ms. Single spacing, which 
is the default, is set by .ss, double spacing is set by .ds, and 
".ms n" is used for multiple spacing. There are (n-1) blank 
lines between text lines for .ms. 

A page e iect insures that no text after the control line 
wi 1 1 be printed on the current page. The current page is 
finished with only footers and footnotes at the bottom, and the 
next text line begins the following page. 
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There are four margi ns on the page vertically. The first 
margin on the page is the number of blank lines above the first 
header/ and is set by the .ml control line. The second, set by 
,m2, concerns the number of lines between the last header and the 
first line of text. The third is between the last line of text 
and the first footer, set by ,m3. The fourth is below the last 
footer, set by .mh . The default for the first and fourth margins 
is four lines; for the second and third, the default is two 
1 i nes . 

As the output is being prepared, a page number counter is 
kept. This counter can be incremented or set by the user. The 
current value of the counter can be used in a header or footer 
through the use of the symbol . A page is called odd (even) 
if the current value of the counter is an odd (even) number. 

A header is a line printed at the top of each page. A 
footer is a line printed at the bottom of each page. A page may 
have up to twenty headers and twenty footers. Headers are 
numbered from the top down, footers from the bottom up. The two 
groups are completely independent of each other. Provision is 
made for different headers and footers for odd and even numbered 
pages. Both odd and even headers (footers) can be set together 
by using .he (.fo). They are set separately by using .eh, .oh, 
.ef, and .of. 

A header/footer definition control line has two arguments, 
the 1 i ne number (denoted in the control line descriptions as 
M #"), and the ti tie . 

The line number parameter of the control line determines 
which header or footer line is being set. If the number is 
omitted, it is assumed to be 1, and all previously defined 
headers or footers of the type specified (odd or even) are 
cancelled. Once set/ a line is printed on each page until reset 
or cancel 1 ed. 

The title part of the control line begins at the first 
non-blank character after the line number. This character is 
taken to be the delimiting character, and may be any character 
not used in the rest of the title. If the delimiting character 
appears less than four times, the missing last parts of the title 
are taken to be blank. The three parts of the title are printed 
left justified, centered, and right justified, respectively, on 
the line. Any or all parts of the title may be null. 
Justification and centering of a header or footer line are 
derived from the line length and identation in effect at the time 
of the definition of the header or footer, and will be used 
whenever that line is output, regardless of the values at the 
time of use. 



(c) Copyright, 1972, Massachusetts Institute of Technology 
All rights reserved. 



MULT ICS PROGRAMMERS' MANUAL 



runoff 



Page 7 
8/15/72 



Omitting the title in the control line cancels the header or 

footer with that number, including its space on the page. A 

blank line in the header or footer may be achieved by a title 

consisting entirely of four delimiting characters. Omitting both 

number and title cancels all headers or footers of the type 
speci f i ed. 



Fxpressions and Expression Evaluation 

An express i on may be either ar ? thmet i c or s tr i ng . and 
consists of numbers and operators in appropriate combinations. 
All operations are performed in integer format, except that 
string comparisons are performed on the full lengths of the 

strings. 

Operators in order of precedence: 

" (bit-wise negation), - (unary) 
*/ // £ (remainder) 
+, - (binary) 

=, <, >, t. <, > 

(comparison operators, yield -1 (true) or 

0 (false)) 
& (bit-wise AND) 

| (bit-wise OR), = (bit-wise equivalence) 



Parentheses may be used for grouping. 
Blanks are ignored outside of constants. 



Octal numbers consist of followed by a sequence of 

octal digits. 

String constants are surrounded by the double quote 
character; certain special characters are defined by 
multiple character sequences beginning with the 
character *, as follows: 



** yields asterisk-character 

*" double-quote-character 

*b backspace character 

*n new-line character 

*t horizontal tab character 

*s space character 

*c nnn character whose decimal value 

i s nnn (1 to 3 digits) 



Concatenation of strings is performed by the 
juxtaposition of the strings involved, in order, left 
to right. 



(c) Copyright, 1972, Massachusetts Institute of Technology 
All rights reserved. 



runoff 



MULT ICS PROGRAMMERS 1 MANUAL 



Page 8 



For positive i , J< , 

str i ng_express ion( i ) 

and 

string_ express ion( i , k) 

are equivalent to the PL/I substr built-in function 
references 

substr (str i ng_express ion, i) 

and 

substr (str i ng_express ion, i, k) 
respectively. 

For negative X/ the substring is defined as starting -X 
characters from the rightmost end of the string; for 
negative k, the substring ends -k characters from the 
end of the string. 

Evaluation of substrings takes place after any 
indicated concatenations; string operations have higher 
precedence than all the binary operations. 

In any context other than a ".sr" control line or in a 
string comparison, a string expression is converted to 
an integer in such a way that a one-character string 
results in the ASCII numeric value of the character. 

Expression evaluation takes place under the following 
cond i t ions : 

1) In .sr and . ts control lines; 

2) In all control lines which accept an "n" or "in" 
argument . 

Def i n t t ion and Subs t ? tu t i on of Var i abl es 

Variables may be defined by the use of the .sr control line; 
their values may be retrieved thereafter by a symbolic reference . 
Names of the variables are composed of the upper- and lower-case 

alphabetic characters, decimal digits, and with a maximum 

length of 361 characters. 'When a variable is defined, it is 
given a type based on the type of the expression which is to be 
its value, either arithmetic or string. Variables which are 
undefined at the time of reference yield the null string, which 
is equivalent to an arithmetic 0. 
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in substitution of variables/ the name of the variable is 
enclosed by other occurrences of the character 

encountered during substitution of variables are replaced by the 
value of the page counter; if a character is to occur in the 
resulting output, it must be coded as "%% u (but see also .cc). 

Substitution of variables may occur 

1) In expressions if a is found as either the first or 
second character following the spacing after the 
control word (substitution of variables takes place 
before expression evaluation); 

2) In ,ur control lines; 

3) In all titles ( l partl , part2 'part3' ), whether in 
header/footer control lines, or as equation lines. 

Many of the variables internal to runoff are available to 
the user (a complete list will be found at the end of this 
document); these include control argument values (or their 
defaults), values of switches and counters, and certain special 
functions. However, the user need not worry about naming 
conflicts, since an attempt to re-define an internal variable 
that is not explicitly modifiable will merely make it 
inaccessible to the user, but will cause no harm to the operation 
of the command. 

Two special builtin symbols in runoff are provided for use 
in footnote and equation numbering: "Foot" contains the value of 
the next footnote number available (or the current footnote if 
referred to from within the text of the footnote), and "Eqcnt" is 
provided for equation numbering. The value of "Foot" is 
incremented by one when the closing .ft of a footnote is 
encountered. Any reference to "Eqcnt" provides the current 
value, and causes its value to be incremented by one 
automatically; thus its value should be assigned to a variable, 
and the variable should then be used in all further references to 
that equation number. 
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Uef aul t Condi t ions 

When no control words are given, runoff prints the text 
single spaced/ right adjusted, with no headers, no footers, and 
no page numbers. 

If page numbers are substituted in headers or equations, 
they will be arab i c. 

A page consists of 66 lines, numbered 1 through 66. The 
first line is printed on line 7, and the last on line 60, if no 
headers or footers are used. If headers are used, there will be 
four lines of top margin, the headers, two blank lines, and then 
the text. If footers are used, there will be two lines skipped 
after the text, footers printed, and four lines of bottom margin. 

A line is 65 characters long; the left margin is that of 
the typewriter. The output is compatible with whatever is normal 
for the device from which the runoff command is executed. The 
entire segment is printed, with no wait before beginning or 
between pages. 
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Control L i ne Formats 

This section gives a description of each of the control 
words which may be interspersed with the text for format control. 
Control lines do not cause an automatic break unless otherwise 
specified. Arguments of the control words are in the following 
f o rm : 



# integer constant 

n integer expression 

in integer expression preceded by optional + or 

<expression> arbitrary expression (string or integer) 

c character 

cd character pair 

f segment name 

'partl'parta'partS 1 

a title whose parts are to be left justified, 
centered, and right justified respectively. 



(bl ank 1 i ne) 

A blank line occurring in the text is treated as if it 
were a n .sp 1" control line. 

.ad Adjust: text is printed right justified. Fill mode 

must be in effect for right justification to occur. 
Fill mode and adjust mode are the default conditions. 
This control line causes a break. 



.ar Arab i c numerals: when numeric variables are 

substituted into text or control lines as a result of a 
,ur control line, or into a title or equation as it is 
printed, they are in arabic notation. This is the 
default condition. 

.bp Begin nage: the next line of text begins on a new page 

of output. This control line causes a break. 

.br Break : the current output line is finished as is, and 

the next text line begins on a new output line. 

.cc c Control character: this control line changes the 
character used to surround the names of symbolic 
variables when they are referenced to c. The default 
special character is . The character specified by c 
must thereafter be used to refer to symbolic variables, 
while percent signs are treated literally. ".cc % u or 
.cc restores the percent sign as the special character. 
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,ce n Cejiter; the next si text lines are centered. if n Is 

missing/ 1 is assumed. This control line implies 
n .ne n" (or M .ne 2n" if doubl espac i ng ) so that all 
lines centered will be on the same page. A break 
occurs . 

.ch cd.. Characters : each occurrence of the character c. will be 
replaced in the .chars segment by the character sL* set 
off by color-shift characters. If the d. character is 
blank/ or an unpaired c_ character appears at the end of 
the line/ the c_ character will not be flagged, and will 
occur as itself in the .chars segment/ or not at all if 
no other character on the line was flagged. 

.ds Double s_pace: begin double spacing the text. This 

control line causes a break. 

.ef # 1 partl'parta'partS 1 

Even footer: this defines even page footer line 
number £. See the section entitled Termi nologv . 

.eh # 'partl'partZ'partS 1 

Even header: this defines even page header line number 
£. See the section entitled Termi nologv. 

.eq n Equat i on : the next n text lines are taken to be 

equations. If n is missing/ 1 is assumed. This 
control line implies n .ne n" (or ".ne 2n" if 
doubl espac i ng) so that all equations will be on the 
same page. The format of the equations should be 
, partl , part2 , part3 , just as in headers. 

.ex text Execute : the remainder of the control line ( text ) is 
passed to the Multics command processor. Substitution 
of variables may occur if the first or second character 
of text is 

.fh 'partl'pa^'partS' 

Footnote header: before footnotes are printed/ a 
demarcation line is printed to separate them from the 
text. The format of this line may be specified through 
the title in the .fh control line. This title is 
printed in the same manner as headers. The default 
footnote header is a line of underscores from column 
one to the right margin. 
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.fi £j_l 1 : this control line sets the fill mode. In fill 

mode/ text is moved from line to line to even the right 
margin, but blanks are not padded to justify exactly. 
This is the default condition. Since right 
justification is also the default condition, getting a 
slightly even right margin without adjustment is ■ 
accomplished by use of the .na control line. This 
control line causes a break. 



.fo # 'parti 1 partZ'partl* 

Footer : even and odd footers are set at the same time; 
this is equivalent to 

.ef # 'partl'pa^ 1 part3 f 

.of # l partl'part2 , part3 l 
See the section entitled Termi nologv . 



fr c Footnote reset: this control line controls 

numbering according to the argument c_. 
values of this argument are: 

t Footnote counter is reset at the top 
page. This is the default condition, 
f Footnote counter runs continuously through 
text. 

u Suppresses numbering on the next footnote. 



footnote 
Permi tted 

of each 



the 



ft 



Fpo_£note: when .ft 
unt i 1 the next .ft 
further text on the 
footnote occurring 
f i t on the page, as 
at the bottom of 



is encountered all subsequent text 
line is treated as a footnote. Any 
.ft line will be ignored. If a 

near the bottom of a page will not 
much as necessary will be continued 

the next page. If a footnote 



reference 
of a page, 
offend i ng 
page. 



occurs in the bottom or next to bottom line 
the current page will be terminated and the 
line printed at the top of the succeeding 



.gb xxx Go back: the current 
the begi nn i ng unt i 1 
found; " xxx " in this 
1 i ne". Process i ng i s 



input segment is searched from 
a line of the form ".la xxx " is 
case means "the rest of the 

continued from that point. 



.gf xxx Go forward: same as .gb, except search forward from 
the current position in the input segment. 
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.he # 'partl'par^^artS' 

Header : even and odd headers are set at the same time. 
This is equivalent to 

•eh # I partl , part2 f part3 l 

.oh # , partl , part2*part3' 
See the section entitled Termi nologv . 

.if f <express i on> 

Insert £ile: the segment with pathname f.. runoff is 
inserted into the text at the point of the ".if f." 
request. The inserted segment may contain both text 
and control lines. No break occurs. The effect is as 
if the control line were replaced by the segment. 
Inserts may be nested to a maximum depth of 30. If a 
second argument is provided, it will be evaluated in 
the same fashion as the expression in .sr, and its 
value and type will be associated with the identifier 
"Parameter"; otherwise the value of "Parameter" 
remains unchanged (or undefined) (prior values of 
"Parameter" are not pushed down). 

• in in I nden t : the left margin is indented ri spaces by 
padding n leading spaces on each line. The right 
margin remains unchanged. By default n. is 0. The 
margin can be reset with another ".in n" request. 
Either .in or ".in 0" resets the original margin. If n 
is preceded by a plus or a minus sign, the indentation 
is changed by n. rather than reset. This control line 
causes a break. 

.la xxx Label : defines the label xxx for use as the target of 
the .gb or .gf control word. 

.li n Lj_teral: this request causes the next n lines to be 

treated as text, even if they begin with ".". If n. is 
not given 1 is assumed. 

±n L>ne length: the line length is set to n. The left 
margin stays the same, and no break occurs. The 
default for n is 65 both initially and if n is omitted 
in the .11 control line. If n is preceded by a plus or 
a minus sign, the line length is changed by n. rather 
than reset. 
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.ma +n Margins: top and bottom margins are set to £ lines. 

If n is preceded by a plus or a minus sign, the margin 
is changed by n. rather than reset. The margin is the 
number of lines printed above the first header and 
below the last footer. The default is four lines. 
This control line is equivalent to 

.ml +n 

.mi* +.n 

.mp in Multiple p.ages: format the output text so that it 
prints on every jith page. This control line is valid 
only for output intended for the bulk printer. The 
default value is 1. 

,ms ±n Multiple space : begin multiple spacing text, leaving 
(n.-l) blank lines between text lines. If n. is preceded 
by a plus or a minus sign, the spacing is changed by n. 
rather than reset. If n is not given, 1 is assumed. 
This control line causes a break. 

.ml ±n Margin 2.: the margin above the first header is set to 
n lines, or changed by n if n is signed. The default 
i s four 1 i nes . 

.m2 ±n Margin 2: the number of blank lines printed after the 
last header and before the first line of text is set to 
n, or changed by n if n is signed. The default is two 
1 i nes . 

.m3 +n Margin 3.: the number of blank lines printed after the 
last line of text and before the first footer is set to 
n., or changed by n. if n. is signed. The default is two 
1 i nes . 

.mi* +n Margin J*: the margin below the last footer is set to n 
lines, or changed by n if n is signed. The default is 
four 1 i nes . 

.na No .adjust: the right margin is not adjusted. This 

does not affect fill mode; text is still moved from 
one line to another. This control line causes a break. 

.ne n Need : a block of n lines is needed. If n. or more 

lines remain on the current page, text continues as 
before; otherwise, the current page is ejected and 
text continued on the next page. No break is implied. 
The default value is 1. 
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.nf Ro f_\ 1 1 : fill mode is suppressed, so that a break is 

caused after each text line. Text is printed exactly 
as it is in the input segment. This control line 
causes a break. 

.of # l partl'part2'part3 l 

Odd footer: this defines odd page footer line number 
#. See the section entitled Termi nologv . 

.oh # 'partl'partZ 1 part3 1 

Odd .header: this defines odd page header line number 
#. See the section entitled Termi nol ogv . 

.op Odd p.age: the next page number is forced to be odd by 

adding 1 to the page number counter if necessary. A 
break is caused and the current page is ejected. 

.pa + n Page : the current line is finished as is (ie a break 
occurs) and the current page is ejected. The page 
number counter is set to n, or is changed by n if ji was 
s i gned. 

.pi n Picture: if n. lines remain on the present page, then n 

lines are spaced over; otherwise/ the text continues 
as before until the bottom of the page is reached, then 
n lines are skipped on the next page before any text is 
printed. Headers are printed normally, and the space 
is below the headers. This option may be used to allow 
for pictures and diagrams. If several .pi control 
lines are used, each n is added to the number of lines 
pending and the total is checked against the space 
remaining on the page. All pending space is allotted 
together. If the total is greater than the usable 
space on a page, the next page contains only headers 
and footers and the rest of the space is left on the 
fo 1 low i ng page . 

.pi in £age length: the page length is set to n. lines. The 
default is 66 lines. If n is preceded by a plus or a 
minus sign, the page length is changed by n rather than 
reset . 

.rd Reach one line of input is read from the stream 

"user_i nput"; this input line is then processed as if 
it had been encountered instead of the . rd control 
line. Thus it may be either a text line or a control 
line; a break occurs only if the replacement line is a 
control line which causes a break, or a text line 
beginning with one or more spaces, or a blank line. 
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. ro Roman numerals: numer ic-to-str ing conversions required 

by an explicit .ur control line (q.v.) or in titles or 
equations will result in roman numerals in the 
evaluated text. This may be reset to arable numerals 
(the default) by use of the ,ar control line. 

. rt £e.£urn: cease processing characters from the current 

input segment. 

. sk n .Skip: H page numbers are skipped before the next new 
page by adding n. to the current page number counter. 
No break in text occurs. This control argument may be 
used to leave out a page number for a figure. If n. is 
not given 1 is assumed. 

.sp n Space : space n. lines. If n. is not given, 1 is 

assumed. If not enough lines remain on the current 
page, footers are printed and the page ejected, but the 
remaining space is not carried over to the next page. 
This control line causes a break. 

.sr name <expression> 

Set reference: associate the value of <expression> 
with the identifier name . The type of name will be set 
to the type of <expression> (either numeric or string); 
if the expression is not provided, or cannot be 
properly evaluated, a diagnostic message will be 
printed, name may be either a user-defined identifier 
or one of the built-in symbols which the user may set. 
(see Bu i 1 1- i n Symbol s below.) 

,ss Single space: begin single spacing text. This is the 

default condition. This control line causes a break. 

.tr cd.. Trans 1 ate : the nonblank character £ is translated to d 
in the output. An arbitrary number of cd. pairs can 
follow the initial pair on the same line without 
intervening spaces. An unpaired £ character at the end 
of a line will translate to a blank character. 
(Translation of a graphic character to a blank only in 
the output is useful for preserving the identity of a 
particular string of characters, so that the string 
will not be split across a line, nor have padding 
i nser ted within it.) 

. ts n Tes.t: process the next input line if the value of n. 

does not equal zero (false). The default value is 1. 
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Type : write xxx (ie the rest of the control line) onto 
the stream "er ror_output n . Substitution of variables 
may occur if the first or second character of xxx is 

II all 

'o • 

Undent : the next output line is indented n spaces less 
than the current indentation. Adjustment, if in 
effect/ will occur only on that part of the line 
between the normal left indentation and the right 
margin. If n is not specified, its value is the 
current indentation value (ie, the next output line 
will begin at the current left margin). This control 
line causes a break. 

JJ.se reference: the remainder of the .ur control line 
( text ) will be scanned, with variables of the form 
"%name%" replaced by their corresponding values 
(converted back to character string form if they were 
numeric). The line thus constructed is then processed 
as if it had been encountered in the original input 
stream (e.g., it may be another control line, including 
possibly another .ur). 

Wail.: read one line from the stream "user_i nput", and 
discard it (cf .rd). 

This line is treated as a comment and ignored. No 
break occurs. 

This line is treated as a comment and ignored with 
respect to the output segment. However, the line is 
printed in the appropriate place in the .chars output 
segment. 
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Summary of Control Arguments and Control Line Formats 



Control arguments 
-ball xi/ "bl a 

-character, -ch 



-device n., ~dv n 
-from n./ -f m n, 
-hyphenate/ -hph 



Convert output to a form suitable for an n 
typebal 1 . 

Create entryname. chars, listing page and line 
numbers with red reminder characters where 
certain characters, normally not printable, 
must be drawn in by hand. 

Prepare output compatible with device n» 

Start printing at the page numbered n.. 

Call user-supplied procedure to perform 
hyphenat ion . 



-indent n, -in n Set initial indentation to n. 

-no_pag i nat ion, -npgn 

Suppress page breaks. 



-number, -nb 
-page n, -pg n 



Print source segment line numbers in output. 
Change the initial page number to n. 



-parameter arg , -pm arg 

Assign arg as 



-pass n 
-segment, -sm 

-stop, -sp 
-to n 

-wait, -wt 



a string to the internal 
variable "Parameter". 

Make n. passes over the input. 

Direct output to the segment or MSF 
"entryname. runout", where entryname is the 
name of the input segment. 

Wait for a carriage return before each page. 

Finish printing after the page numbered n.. 

Wait for a carriage return before the first 
page . 
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Control 1 ine format? 

The following conventions are used to specify arguments of 
control words: 





c 


character 






cd 


character pair 






exp 


express i 


on (either 


numeric or string) 




# 


i nteger 


constant 






n 


i nteger 


express ion 






+ n 


+_ 


indicates update 


by n; if sign not present set to n 




f 


segment 


name 






t 


ti 


tie of 


the form 


■partl'pa^'partS 1 


Reauest 




Break 


Default 


Meaning 


(bl ank 1 i ne ) 


yes 




Equivalent to ".sp 1" 


. ad 






yes 


on 


Right justify text 


. ar 






no 


arab i c 


Arabic page numbers 


.bp 






yes 




Begin new page 


• d r 






yes 




Break/ begin new line 


. cc 


c 




no 




Change special character from % 












to c 


. ce 


n 




yes 


n= 1 


Center next n lines 


. ch 


Cu III! 




no 




Note c in .cnars r i le as a 


.ds 






yes 


off 


Double space 


.ef 


# t 




no 




Defines even footer line # 


. eh 


# t 




no 




Defines even header line # 


.eq 


n 




yes 


n = l 


Next n lines are equations 


.ex 


XXX 




no 




Call command processor with "xxx" 


.fh 


t 




no 


1 i ne of 


underscores 












Format of footnote demarcation 












1 i ne 


.f i 






yes 


on 


Fill output 1 i nes 


.fo 


# t 




no 




Equivalent to: .ef # t 












. Of fr t 


.fr 


c 




no 


t 


Controls footnote numbering: t 












reset each page; "f" continuous; 












"u" numbering suppressed for next 












footnote . 


.ft 






no 




Del imi ts footnotes 


.gb 


XXX 




no 




"go back" to label xxx 


.gf 


XXX 




no 




"go forward" to label xxx 


. he 


# t 




no 




Equivalent to: .eh # t 












.oh # t 


.if 


f exp 




no 




Segment f. runoff inserted at 












point of request; value of "exp" 












assigned to "Parameter" 


. i n 


±n 




yes 


n = 0 


Indent left margin n spaces 


.la 


XXX 




no 




Define label xxx 
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Request 


Break 


Defaul t 


Mean i nz 


. 1 i 


n 


no 


n=l 


Next n lines treated as text 


. 1 1 


±n 


no 


n=65 


Set 1 i ne 1 ength to n 


.ma 


±n 


no 


n = k 


Top and bottom margins set to n 


.mp 


±n 


no 


n = l 


Print only every n-th page 


.ms 


±n 


yes 


n = l 


Multiple space of n lines 


.ml 


+n 


no 


n = h 


Margin above headers set to n 


.m2 


±n 


no 


n=2 


Margin between headers and text 










set to n 


. m d 


+.n 


no 


n = 2 


Margin between text and footers 










set to n 


.mk 


±n 


no 


n = k 


Margin below footers set to n 


. na 




yes 


off 


Do not right justify 


.ne 


n 


no 


n = l 


Need n lines; begin new page if 










not enough remain 


.nf 




yes 


off 


Nofill; break after each input 










1 ine 


.of 


# t 


no 




Defines odd footer line # 


.oh 


# t 


no 




Defines oacl header line # 


.op 




yes 




Next page number is odd 


.pa 


±n 


yes 




Begin page n 


.pi 


n 


no 


n = l 


Skip n lines if n remain; 










otherwise skip n on next page 










before any text 


.Pi 


in 


no 


n=66 


Page length is n 


. rd 




no 




Read one line of text from 










"user_i nput" and process it in 










pi ace of . rd 1 i ne 


. ro 




no 


arab i c 


Roman numeral page numbers 


. rt 




no 




"return" from this input segment 


. SK 


n 


no 


n=l 


Skip n page numbers before next 










new page 


• sp 


n 


yes 


n=l 


Space n 1 i nes 


. s r 


sym exp 


no 




Assign value of "exp" to variable 










named "sym" 


. ss 




yes 


on 


Single space 


. tr 


cd . . . . 


no 




Translate nonblank character c 










into d on output 


. ts 


n 


no 


n = l 


Process the next input line only 










if n is non-zero 


.ty 


XXX 


no 




Write "xxx" onto the stream 










"error_output" 


. un 


n 


yes 


left margin 










Indent next text line n spaces 










less 


.ur 


text 


no 




Substitute values of variables in 



"text", and re-scan the line. 
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Request Break Defaul t Meaning 

.wt no Read one line of text from 

"user_i npu t" and discard it (for 
synchronization with console) 

.* no Comment line; ignored 

no Comment line; ignored, but 

included in .chars output 
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Built-in Symbol s 

Only those symbols marked yes in the Set column may have values 
assigned by the user. 

All symbols are of type Number unless they are specified to be of 
type string. 

Control words and control arguments which affect the values of 
the variables are indicated in parentheses: (x/y) indicates that 
x sets the switch to true (-1), and y sets it false (0); (a) or 
(a, b, c) indicates that it is affected by a or by a, b and c. 



Symbol 



Set 



Val ue 



Ad 
Ce 

CharsTab 1 e 
Charsw 
ConvTab 1 e 

Date 
Devi ce 

DeviceTable 
Eq 

Eqcnt 

ExtraMargi n 
Fi 

Fi 1 eName 

Fi 1 esw 

Foot 
FootRef 

Fp 



yes 
yes 
yes 



yes 

yes 

yes 
yes 



yes 
yes 

yes 



Adjust (.ad/.na) 

Number of lines remaining to be 
centered (.ce) 
Translation table 



for 



. chars 



is being created 



output . 
TrTable 

runoff; 

to be 
-bal 1, 

phys i cal 



segment output (String) (.ch) 
".chars" file 
(-character) 

Translation table for 
Product of DeviceTable and 
(String) (.tr, -device) 
Date of this invocation of 
format is mm/dd/yy (String) 
Type of device output is 
formatted for (-device, 
-segment ) 

Translation table for 
device (String) (-device) 
Equation line counter (.eq) 
Equation reference counter 

(incremented each reference) 
Indent entire text this many 
(-segment/ -device, -indent) 
Fill switch (.fi/.nf) 
Name of current primary 
segment (String) 
True if output is going 
segment (-segment) 
Footnote counter (.ft, .fr) 
Footnote reference string 
footnote body (String) 
First page to print (set at the 
beginning of each pass to the value 
of From) 



spaces 



input 



to 



i n 
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Symbol 



Set 



Val ue 



Fr 

From yes 
Ft 

Hyphenating yes 
In 

I nputF 1 1 eName 
I nputL i nes 
Li nesLef t 
LI 

Lp yes 

Mai 
Ma2 
Ma 3 
Ma4 
Ms 

Mul ti plePagecount 

Nes t i ngDepth 

Nl 

NNp yes 
NoFtNo 

NoPaging yes 
Np yes 
PadLef t 

Parameter yes 
Passes yes 

Pi 
PI 

Print yes 
Pr i ntersw 

Pr i n tL i neNumbers yes 



Footnote counter reset switch 
Control argument value (-from) 
Footnote processing switch (.ft) 
True if an attempt to break a word 
should be made (-hyphenate) 
Indent to here (.in) 
Name of current input segment 
(String) (.if) 

Current line number in current 
source file 

Number of usable text lines left on 

this page 

Line length (.11) 

Last page to print (initialized 

each pass from To) 

Space above header (.ma/ .ml) 

Space below header (.m2) 

Space above foot (.m3) 

Space below foot (.ma/ .mh) 

Spacing between lines (ss = 1, 

ds = 2/ etc.) ( .ms/ . ss, .ds) 

Form feeds between pages to printer 

( .mp) 

Index into stack of input files 
(.if) 

Last used line number 

Next page number (-page/ .pa) 

True to suppress number on next 

footnote reference (.fr) 

True if no pagination is desired 

(-no_pagi nation) 

Current page number (.pa, -page, 
initialized each pass from Start) 
Alternate left/right padding switch 
(.un, .ad) 

Argument passed during insert 
processing (-parameter/ .if) 
Number of passes left to make (= 1 
when printing is being performed) 
(-pass) 

Space needed for pictures (.pi) 

Page length (.pi) 

Whether or not to print 

((Fp 1 Np 1 Lp) & (Passes < 1) ) 

Output is intended for bulk printer 

(-device/ -segment) 

True if source line numbers are to 

be printed in output (-number) 
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Svmbol 


Set 


Roman 




Sel sw 




Start 


yes 


S topsw 


yes 


TextRef 


yes 


Time 




To 


yes 


TrTable 


yes 


Un 




Wai tsw 


yes 
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value 

Roman numeral pagination C.ro/.ar) 
True if typeball other than 963 is 
being used (-bal 1 ) 

Initial page number (-page, -start) 
Stop between pages of output 
(-stop) 

Footnote reference string in main 
text (String) 

Local time, in seconds, since 

January 1, 1901. 

Last page to be printed (-to) 

Translation table for user-supplied 

substitutions (String) (.tr) 

Undent to here (.un) 

Wait for input before printing 

first page (-wait) 
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Hyphenat i on Procedure Call i ng Sequence 

The runoff command provides a means whereby a user-supplied 
program may be called whenever the space available on a line is 
less than the length of the next word (including attached 
punctuation, if any). The mechanism is activated by use of the 
-hyphenate control argument, and the PL/ I calling sequence is 
provided below. 



declare hyphenate_word_ en try(char (* ) 
f i xed bin); 



unaligned, fixed bin, 



call hyphenate_word_(str ing, space, break); 



1) string 

2) space 



is the text word which 
( Input) 



i s 



to be split. 



is the number of print positions remaining in 
the line. (Input) 



3) break 



is the number of characters from the word 
that should be placed on the current line; 
it should be at least one less than the value 
of space (to allow for the hyphen), and may 
be 0 to specify that the word is not to be 
broken. Thus if the word "calling" is to be 
split, and 6 spaces remain in the line, the 
procedure should return the value h 



(adjustment 
(Output) 



s performed after hyphenation). 
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Name : runoff__abs, rfa 



This command submits an absentee request to process text 
segments using the runoff command. The absentee process 
prepares, in manuscript form, an output segment for each text 
segment and stores each output segment in the user's working 
directory. The name of the output segment is the name of the 
text segment with the suffix ".runoff" replaced by ".runout". 
The absentee process then uses the dprint command to queue each 
output segment for printing and deletion. Printing and deletion 
can be withheld if desired. If the -output__f i le control argument 
(one of those recognized by the enter__abs__request command) is not 
specified, the absentee process's output segment is placed in the 
user's working directory with the name pathi .absout, where pathl. 
is the first argument of the command. (See Usage below.) 



Usage 



runoff_abs pathl ••• pathn. -rf_args- -ear_args- -rfa_args- 



1) path! 



is an absolute or relative path name 
specifying the segment to be processed by the 
runoff command. It need not specify the 
".runoff" suffix, which must appear in the 
actual segment name, however. If more than 
one path name is given, each segment is 
considered a separate runoff task. 



2) rf_args 



can be one or more control arguments accepted 
by the runoff command. See the MPM write-up 
for runoff. 



3) ear_args 



k) rfa_args 

-queue n, -q a 



can be one or more control arguments accepted 
by the enter_abs_reques t command. The 
-brief (-bf) control argument is not 
permitted here. See the MPM write-up for 
enter_abs_request . 



can be one of the following: 



specifies 
is to be 
is 3 . 



n wh i ch priori ty 
placed (n <. 3) . 



queue the request 
The default queue 



-copy a/ -cp a 



specifies the number of copies of the segment 
to be dprinted (n <. k) . The default is 1. 
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-hold specifies that the output segments created by 

runoff should not be queued for printing or 
deleted. Each output segment is formatted 
for printing on an IBM 27U1 terminal, with a 
963 type ball, unless some other output form 
is specified by one of the runoff control 
arguments . 

Notes 

When doing several runoffs, it is more efficient to give 
several path names in one command, since only one process is set 
up with one command. Thus the cost of process initialization 
need be incurred only once. 

Control arguments and path names can be mixed freely in the 
command line. All control arguments apply to all path names. An 
unrecognizable control argument causes the absentee request not 
to be submitted. 

The runoff_abs command expects each segment to be processed 
to have the suffix ".runoff", whereas early versions of the 
runoff command accepted segments without such a suffix. If any 
of the input text segments cannot be found, no absentee request 
is submitted. 
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safety_sw_of f 



Command 
3/12/73 



Name : saf ety_sw_pf f , ssf 

This command turns off the safety switch of a directory or a 
segment/ thus permitting the segment or directory to be deleted. 
See the MPM Reference Guide section, Segment, Directory and Link 
Attributes, for a description of the safety switch. 

Usage 

safety_sw_of f pathname!. ... pathnamen 

1) pathname! is the path name of the segment or directory which 
should have its safety switch turned off. If it 
is "-wd" or f, -working__di rectory" or omitted, then 
the working directory is assumed. The star 
convention may be used. 

Examples 

safety_sw__of f test. pi 1 check. fortran 

will turn off the safety switch of the segments test.pl 1 and 
check. fortran 

ssf *.temp__dir 

will turn off the safety switch of all directories and segments 
with a two component name which ends in temp_dir. 
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safety__sw_on 



Command 
3/12/73 



Name : saf e ty_sw_on / ssn 



This command turns on the safety switch of a directory or a 
segment/ thus preventing deletion of the segment or directory. 
See the MPM Reference Guide section, Segment, Directory and Link 
Attributes, for a description of the safety switch. 

Usage 



safety_sw__on pathname! ... pathnamen 

1) pathname! is the path name of the segment or directory which 
should have its safety switch on. If it is "-wd" 
or "-work ing_di rectory" or omitted then the 
working directory is assumed. The star convention 
may be used. 



Examples 



saf ety__sw_on *.pll 



will turn on the safety switch of all segments found in the 
working directory with two component names ending in .pll. 



ssn 



will turn on the safety switch in the working directory. 
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setbi t count 



Command 
2/9/73 

Names : set_bi t__count, sbc 

This command sets a specified bit count on a specified 
segment entry, and changes the bit count author for that entry to 
be the user who invoked the command. 

ii saee 

set__bi t_count pathl countl. ••• pathn countn 

1) pathj_ is the path name of the segment whose bit count is to 

be set. If pathx is a link, the branch linked to 
will have its bit count set, 

2) countl is the bit count, in decimal, desired for pathj.. 
Notes 

Setting the bit count on a directory is permitted, but 
several system modules will then regard the directory as a 
mul ti -segment file. 

The user must have modify access on the directory containing 
the segment for which the bit count is to be set. 
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set_com_J ine 



Command 
2/13/73 



Name : set_com__l i ne, scl 

The set_ com_line command allows the user to change the 

maximum size of expanded command lines. The default size is 128 

characters. An expanded command line is one obtained after all 
active strings have been processed. 

Usage 

set_com_Jine -size- 

1) size is the new maximum expanded command line size. If size 
is not specified, the line size is restored to its 
default of 128 characters. 

Notes 

The get_com_line command prints on the user's terminal the 
current value of the maximum size of expanded command lines. 

For a discussion of the command language (including the 
treatment of active strings), see the MPM Reference Guide 
section, The Command Language. 
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se t_da rtmou t h_l Ibrary 



Command 

Standard Service System 
11/03/70 



Name ; set_da rtmouth_l i bra ry, sdl 

This command allows the user to specify a directory to be 
searched before the Dartmouth system 1 ibrary is searched in 
reference to Basic library programs. The library is searched 
whenever *** is appended to a program name within a Basic 
program. 

Usa ge 

set_dartmouth_l ibrary -pathname- 

1) pathname is the pathname of the directory to be used as the 
user's library. If no pathname is given / the library pathname is 
set to null and no user library is searched. 

Note that if a program in the user's library has the same 
name as a system library routine, the user's version is the one 
used. 



(END) 
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set_i acl_ di r 



Command 
3/29/73 



Name : set_i acl_di r, sid 

This command adds entries to a directory Initial Access 
Control List (Initial ACL) in a specified directory/ or modifies 
the access mode in an existing Initial ACL entry. A directory 
Initial ACL contains the ACL entries to be placed on directories 
added to the directory. For a discussion of Initial ACLs, see 
the MPM Reference Guide section/ Access Control. 



set_iacl_dir pathname model acnamel ... moden. acnamea -ca- 



1) pathname 



2) model 



specifies the directory in which the 
directory Initial ACL should be changed. If 
it is "-wd" or "-worki ng_di rectory" then the 
working directory's Initial ACL is assumed. 
If an entry for acnamel already exists, then 
its mode is changed to model/ otherwise 
acnamel with model is added to the ACL. The 
star convention may be used. 



may 
sma" 

Kl — tf 



is the mode associated with acnamel. It 
consist of any or all of the letters 11 
(status/ modify/ append) except that if "m 
is given/ "s" must also be given. To 
specifically deny access to acnamel/ 
or "null" should be used for model. 



ii n ii 
n / 



till 



3 ) acnamel 



is an access control 
model to pathname. 



name which is permitted 
If the last modei has no 



acnamel following it/ the user's name and 
project are assumed, acnamel must be of the 
form person. project. tag. If one or more of 
the components is missing/ then they are 
assumed to be "*". Any component missing on 
the left must be delimited by periods. The 
periods to the right may be omitted. 



k) ca 



may be the control argument -ring (-rg). It 
may appear anywhere on the line, except 
between a mode and its associated acname, and 
affects the whole line. If present it must 
be followed by a digit/ where user's ring ± 
digit <. 7/ which specifies which ring's 
Initial ACL should be affected. If the 
control argument is not given the user's ring 
is assumed. 
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Examples 

set_J acl_di r listings sm * 

will change the mode or add an entry to the directory Initial ACL 
in the directory listings with the mode "sm" being given to *.*.* 
(everyone. ) 

sid -wd sa Jones . Facul ty 

will add to the directory Initial ACL in the working directory an 
entry with mode "sa" for Jones . Facul ty. * if that entry does not 
exist; otherwise it will change the mode of the Jones . Facul ty. * 
entry to "sa." 
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set_i acl_seg 



Command 
3/29/73 



Name ; set_J acl_seg, sis 

This command adds entries to a segment Initial Access 
Control List (Initial ACL) in a specified directory, or modifies 
the access mode in an existing Initial ACL entry. A segment 
Initial ACL contains the ACL entries to be placed on segments 
added to the directory. For a discussion of Initial ACLs see the 
MPM Reference Guide section. Access Control. 

Usage 

set__i acl_seg pathname model acnamel. ... moden, acnamen. -ca- 

1) pathname specifies the directory in which the segment 

Initial ACL should be changed. If it is 
"-wd" or "-worki ng_di rectory" then the 
working directory's Initial ACL is assumed. 
If an entry for acnamel already exists, then 
its mode is changed to modej_; otherwise 
acnamej_ with model is added to the Initial 
ACL. The star convention may be used. 

2) model is the mode associated with acnamej_. It may 

consist of any or all of the letters "rew" 

(read, execute, write.) To specifically deny 

access to acnamel, "n", "", or "null" should 
be used for model. 

3) acnamel is an access control name which is permitted 

model to pathname. If the last model has no 
acnamel following it the user's name and 
project are assumed, acnamel must be of the 
form person. project . tag. If one or more of 
the components is missing, then they are 
assumed to be . Any components missing on 
the left must be delimited by periods. The 
periods to the right may be omitted. 

k) ca may be the control argument -ring (-rg). It 

may appear anywhere on the line except 
between a mode and its associated acname, and 
affects the whole line. If present it must 
be followed by a digit, where user's ring £ 
digit <. 7, which specifies which ring's 
Initial ACL should be affected. If the 
control argument is not given, then the 
user's ring is assumed. 
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Examples: 

set_iacl_seg test rew * 

will change the mode or add an entry to the segment Initial ACL 
in the directory test/ with the mode rew being given to *.*.* 
( everyone. ) 

sis -wd re Jones . Facul ty -rg 5 

will add to the segment Initial ACL for ring 5 in the working 
directory, an entry with mode re for Jones . Facu 1 ty. * if that 
entry does not exist; otherwise it will change the mode of the 
Jones . Facul ty. * entry to "re". 
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set search dirs 



Command 
Development System 
6/30/72 



Name : set_search_d i rs, ssd 



The se t_search_d i rs command allows users to insert search 
directories after the working directory in the default search 
rul es . 

Usa ge 

set_search_d i rs argl. ... argn. 
1) argl are the pathnames of the directories to be searched. 
Notes 

The current maximum number of arguments is thirteen. 

See also set__search_rules and pr i n t_search_ru 1 es in the MPM. 

Searching is expensive in machine time, so the fewer 
directories searched, the better. 



(c) Copyright/ 1972, Massachusetts Institute of Technology 
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set search rules 



Command 
Development System 
6/25/71 



Name : set_search_ru1 es, ss'r 

The se t_search_ru 1 es command allows the user to set his 
search rules to suit his individual needs with only minor 
rest r i ct ions . 

Usage 

set_search_rul es pathname 

1) pathname is the pathname of a segment containing the ASCII 

representation of the search rules. 

Notes 

The allowed search rules are absolute pathnames of 
directories to be searched and the following key words: 

1) i n i t iated_segments check the already initiated 

segments; 

2) ref erenc i ng_d i r search the parent directory of the 

segment making the reference; 

3) working d i r search the working directory; 
k) home_dir search the home directory; 

5) process_dir search the process directory; 

6) systerrM i brar i es search the default system 

1 i brar i es . 

Currently, i n i t i a ted_segments must be the first search rule. 
If the user decides not to put systerrM i bra r i es in his search 
rules, then many standard commands cannot be found. 

There must be one rule per line. A maximum of 21 search 
rules is allowed. Leading and trailing blanks are allowed but 
embedded blanks are not allowed. 

See also pr i nt_search__rul es and set_search_d i rector i es in the 

MPM. 

Warning: searching is expensive in machine time so the fewer 
directories searched the better. 



(END) 
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setacl 



Command 
3/1/73 



Name : setacl/ sa 

This command adds entries to an Access Control List (ACL) or 
modifies the access mode in an existing ACL entry of either a 
segment or a directory. See the MPM Reference Guide section/ 
Access Control/ for a discussion of ACLs. 



"sage 

setacl pathname model, acnamei . . . moden. -acnamen- 

1) pathname specifies the segment or directory for which the 
ACL should be changed. If it is "-wd" or 
"-worki ng_di rectory", then the working directory 
is assumed. If an entry for acnamei already 
exists, then its mode is changed to modei, 
otherwise acnamei with modei is added to the ACL. 
The star convention may be used. 



2) model is the mode associated with acnamei. For 

directories it may consist of any or all of the 
letters "sma" (status, modify/ append) with the 
requirement that if "m" is given, "s" must also be 
given. For segments it may consist of any or all 
of the letters "rew" (read, execute, write.) To 
specifically deny access to acnamei, "n", "", or 
"null" should be used for modei. 



3) acnamei is an access control name which is permitted modei 
to pathname. If the last modei has no acnamei 
following it/ the user's name and project are 
assumed. acnamei must be of the form 
person. pro ject. tag. If one or more of the 
components is missing/ then they are assumed to be 
"*". Any component missing on the left must be 
delimited by periods. The periods to the right 
may be omi tted . 
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Fxamples 

setacl *. pi 1 rew * 

will change the mode or add an entry to the ACL of every segment 
in the working directory that has a two component name with a 
second component pll, giving the mode "rew" to *.*.* (everyone.) 

sa -wd sm Jones . Facul ty 

will add to the ACL of the working directory an entry with mode 
"sm" for Jones . Facul ty. * if that entry does not exist; otherwise 
it will change the mode of the Jones . Facul ty. * entry to "sm." 



© 



Copyright, 1973/ Massachusetts 

and Honeywe 1 1 
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Command 
Development System 
11/0^/70 



Name ; sort_file, sf 



The sort_file command may be used to sort the lines in an 
ASCII file in ascending order according to the ASCII collating 
sequence. The resorted file replaces the previous contents of 
the specified file. 

Usage 

sort_.fi le path 

1) path specifies the pathname of an ASCII file to be sorted 
line by line. The resorted contents of the file will 
replace the previous contents of the file. (The 
length of the file will, of course, remain 
unchanged. ) 

Lines of unequal length are compared by assuming the shorter 
line to be padded on the right (after the new-line character) 
with following blanks. 

The lines of the original file are resorted using temporary 
segments in the process directory. The original file is not 
modified until the last moment. 



(END) 
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start 



Standard 



Command 
Service System 
4/20/72 



Name : start/ sr 

The start command is employed after the quit button has been 
pressed in order to resume execution of the user's process from 
the point of interruption. It may also be used to resume 
execution after an unclaimed signal/ provided that the condition 
which caused the unclaimed signal either is innocuous or has been 
corrected. It restores the attachments of user_input/ 
user_output/ and error__outpu t/ and the mode of user_i/o to what 
they were at the time of the interruption/ unless the -no_restore 
control argument is given (see below). 

Usage 

start -contro1_argument- 

1) control_argument is either -no__restore or -nr. If present/ 

it indicates that the standard I/O 
attachments should not be restored. 

Note s 

This command may be issued immediately after a quit signal. 
It may also be issued later/ but only if a hold command was given 
immediately after the quit signal and no subsequent release 
command was given. 

If there is no suspended computation to re-start/ the 
command prints the message "start ignored". 

See also the MPM Reference Guide section on The Multics 
Command Language Environment. 
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status 



Command 
3/12/73 



Name : status, st 



The status command prints selected 
information about the storage system entry 



detailed file 
speci f i ed. 



status 



Usage 



status path! 



1) pathi 



2) control_argi 



-all/ -a 



-date, -dt 

-name, -nm 
-mode/ -md 



pathn -control_argl- 



- control _arg.n- 



is the path name of the segment/ directory/ 
mul ti -segment file/ or link for which status 
information is desired. The default path 
name is the working directory which may also 
be specified by "-wd". The star convention 
may be used. 

is chosen from the following list of control 
arguments. The control arguments may appear 
anywhere on the line and are in effect for 
the whol e 1 i ne. 



The control arguments 
directories are: 



for segments and 



all relevant information 
hcs_$status_Jong; i.e., the 
names, unique id, date used, 
date branch modified, date 



returned by 
type of entry, 
date modified, 
dumped, author, 



bit count author (if different from author), 
device, bit count, records used, current 
blocks (if different from records used), max 

length in words (if type is segment), safety 
switch (if it is on), user's mode and ring 
brackets, and copy switch (if it is on); 



all the dates on 
date modified, 
dumped; 



the entry; i 
date branch 



e., date used, 
modified, date 



all the names on the entry; 

the user's mode, ring brackets and safety 
swi tch (if it i s on) ; 



-device, -dv 



the device id; 
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-lengthy -In 



-author / -at 



-type/ -tp 



-all/ -a 



-date/ -dt 

-name/ -nm 
-author/ -at 
-type, -tp 



Notes 



the bit count, the number of records used, 
the current blocks (if different from records 
used) and the max length in words (if type is 
segment) ; 



the author of the entry and the bit 
author (if different from author); 



count 



the type of entry (segment, directory 
mul ti -segment file, link). 

If no control argument is specified, the 
following information is given for segments 
and directories: names/ type/ date used, date 
modified, date branch modified, bit count, 
records used, user's mode. 

The control arguments for links are: 

all relevant information return by 
hcs_$status_long, i.e., the path name of the 
entry linked to, names, unique id, date link 
modified, date dumped, and the author of the 
link; 

all the dates, i.e., date link modified, date 
dumped; the path name of the entry linked to; 

all the names on the link; 

the author of the link; 

the type of entry (link) and the path name of 
the entry linked to. 

If no control argument is specified, the 
following information is printed for links: 
the pathname of the entry linked to, names, 
date link modified, date dumped. The -mode, 
-device, and -length control arguments will 
be ignored for links. 



Any zero-valued dates will not be printed. 

Directories that have been used to implement mul t i -segment 
files will be labelled as suc K 
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Ex amp 1 es 

1) status >Federal >Adams 

names: Washington 
Test_Jss 
Adams 

type: 

unique id: 
date used: 
date modified: 
branch modified: 
author : 

bit count author: 
device: 
bit count: 
records used: 
safety sw: 
mode: 

ring brackets: 



-all 



dl rectory 

76457601*6673 

01/27/73 1459.0 est Wed 

01/27/73 1459.0 est Wed 

11/19/72 1542.6 est Thu 

Hami 1 ton . Mu 1 1 i cs . a 

Dumper . SysDaemon . a 

DSU-190 

0 

6 

on 
rew 
5, 5 



2) 



status -type -mode -date newtest.* 
>States>Washi ngton>newtest . pi 1 



type: 

date used: 
date modified: 
branch modified: 
date dumped: 
mode: 

ring brackets: 



segment 

01/26/73 2145.0 est Tue 
01/13/73 1630.0 est Wed 
01/13/73 1626.7 est Wed 
01/14/73 0305.4 est Thu 
rew 

k, 5, 5 



>States>Washi ngton>newtest . list 



type: 

1 i nks to : 

date 1 i nk mod i f i ed : 



1 ink 

Federal > Jef f erson>newtest . 1 i st 
01/26/73 2139.3 est Tue 
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termi nate 



Command 
2/12/73 



Names : terminate/ tm 

termi nate_segno, tms 

terminate_ref name, tmr 

termi nate_single__ref name, tmsr 

This command allows the user to remove a segment from his 
address space. It is most useful when recompiling procedures so 
that the new version may be invoked with no linkage 
complications. Therefore it is called automatically by the 
Multics compilers. The user may also call this command directly 
in order to test various versions of a procedure. Generally, the 
links to a segment are not reset unless that segment has a 
linkage section. However, they are always reset for the 
termi nate_ref name (tmr) and termi nate_single_ref name (tmsr) 
entr i es . 

Usage 

terminate namel ... namen 
1) namel is the path name of a segment to be terminated. 



Entrv : termi n at e_segno, tms 

This entry allows termination by segment number. 

Usage 

termi nate_segno segnol ... segnon 

1) segnol is the segment number (in octal) of a segment to be 
terminated. 

Entrv : termi nate_ref name, tmr 

This entry allows termination by reference name. The 
segment itself is terminated, not merely the particular reference 
name specified. 

Usage 

termi nate_ref name namel ... namen 
1) namel is the reference name of a segment to be terminated. 
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Entrv : terminate_single_refname, tmsr 

This entry allows termination of a single reference name. 
Unless the specified reference name is the only one by which the 
segment is known, the segment itself will not be terminated. 

usage 

terminate_single__refname namel ... namea 
1) namei is the reference name to be terminated. 
Notes 

Caution must be exercised when using these commands as one 
may unintentionally terminate a segment of the command language 
interpreter or another critical piece of the environment. The 
usual result is termination of the user's process. 

The star convention is not recognized in any of the above 
commands. 
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trace stack 



Command 
Development System 
8/10/72 



Name : t race__stack, ts 



The track_stack command prints a detailed explanation of the 
current process's stack history in reverse order (most recent 
frame first). For each stack frame / all available information 
about the procedure which established the frame (including, if 
possible, the source statement last executed), the arguments to 
that (the owning) procedure/ and the condition handlers 
established in the frame is printed. 

trace__stack is most useful after a fault or other error 
condition. If the command is invoked after such an error/ the 
machine registers at the time of the fault are also printed/ as 
well as an explanation of the fault and the source line in which 
it occurred if possible. 

Usage 

trace_stack -control__args- 

1) control_args may be selected from the following: 

-brief/ -bf Supress listing of arguments and handlers. 

-long/ - 1 g Print octal dump of each stack frame. 

-depth n, ~dn n Dump only n frames. 
Output Format 



When trace_stack is invoked, it first searches backward 
through the stack for a stack frame containing saved machine 
conditions as the result of a fault. If such a frame is found/ 
tracing will proceed backward from that point; otherwise/ a 
comment is printed and tracing beings with the stack frame 
preceding trace_stack. 

If a machine-conditions frame is found/ track_stack repeats 
the system error message describing the fault. Unless "brief" 
mode was selected, trace_stack also prints the source line and 
faulting instruction, and a listing of the machine registers at 
the time the fault occurred. 



The command then performs a backward trace of the stack, for 
n frames if the "-depth n" argument was specified, or until the 
beginning of the stack is reached. 
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For each stack frame/ trace__stack prints the offset of the 
frame/ the condition name if a fault occurred in the frame/ and 
the identification of the procedure which established the frame, 
if the procedure is a component of a bound segment/ the bound 
segment name and the offset of the procedure within the bound 
segment will be printed also. 

The trace_stack command then attempts to locate and print 
the source line associated with the last instruction executed in 
the procedure which owns the frame (which is either a call 
forward/ or a line which encountered a fault). The source line 
can be printed only if the procedure has a symbol table (that is, 
if it was compiled with the "-table" option) and if the source 
for the procedure is available in the user's working directory. 
If the source line cannot be printed/ trace_stack will print a 
comment explaining why. 

Next/ trace_stack prints the machine instruction last 
executed by the procedure which owns the current frame. If the 
machine instruction is a call on a pll operator/ trace_stack will 
also print the name of the operator. If the instruction is a 
procedure call/ trace_stack will suppress the octal of the 
machine instruction and print the name of the procedure being 
cal led. 

Unless the output mode is "brief"/ trace_stack will next 
list the arguments supplied to the procedure which owns the 
current frame, and list any enabled condition, default and 
clean-up handlers established in the frame. 

If the output mode is "long"/ trace_stack will then print an 
octal dump of the stack frame, with eight words per line. 

Example: 

After a fault which reenters the user environment and 
reaches command level/ a user might type 

hold 

tracers tack 
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truncate 



Command 
11/14/72 



Name : truncate, tc 

This command will truncate a segment to a specified length, 
and reset the bit count accordingly. It resets the bit count 
author for the storage system entry to be the user who invoked 
the command. The segment may be specified by path name or 
segment number. 



"sage 



truncate -control__arg- segid length 



1) -control_arg- 



2) segid 



3) length 



If present, must be -name or -nm, 
that the following segid is in 
name, although it may look like a 



indicating 
fact a path 
number. 



is either a path name or an octal segment 
number. A path name that happens to be an 
octal number should be preceded by the 
control argument -name or -nm. 

is an octal integer indicating the length in 

words to which the segment is to be 

truncated. If no length argument is 
provided, zero will be assumed. 



Notes 

The length argument 
after truncation. Thus, 

truncate alpha 50 



designates the length of the segment 



will truncate all of the segment alpha except the first 50 words 
(i.e., words 0 to 47). The bit count of the segment will be set 
to the truncated length. 

If the segment is already shorter than the specified length, 
its length will be unchanged, but the bit count will be reset to 
the specified length. 
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Command 
2/15/73 



Name : unlink, ul 

The unlink command deletes the specified link entry. For a 
discussion of links see the MPM Reference Guide section. Segment, 
Directory and Link Attributes. 

.Ms age 

unlink pathl ... pathn 
1) pathi specifies a storage system link entry to be deleted. 
Notes 

The user must have modify access in the directory containing 
the 1 i nk. 

The star convention may be used. 

The delete, deleteforce and delete_dir commands may be used 
to delete segment and directory entries. 
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Command 
it/30/73 



Name; v5basic 



The vSbasic command invokes the BASIC compiler to translate 
a segment containing BASIC source code. If the compile option is 
not specified, the compiled code is then executed. 



Usage 

v5basic source_name -option!.- ... -optionn- 



1) source__name is the path name of the segment to be 

translated. The characters .basic may or may 
not appear as part of the path name. They 
must appear/ however/ on the segment itself. 

2) option! is selected from the following list of 

options. The options may appear in any 
order. 



-time Hz ~tm n 



specifies a time limit of jq CPU seconds where 
XI is an integer. When the time limit is 
exceeded, execution stops/ and the user is 
asked if he would like to continue execution. 
If he answers yes, a new timer is set giving 
the user the same amount of time. 



-compi 1 e 



indicates to compile the program and produce 
an object segment rather than immediately 
executing the code. The compiled object 
segment is saved in the user's working 
directory with the characters .dobj appended 
in place of .basic. The object segment is 
not a Multics standard object segment and can 
only be executed using the basic_run command. 



-library/ -lb 



indicates that the Dartmouth library is to be 
searched for the source segment. No other 
directory is searched. 



Note? 

This implementation of BASIC is described in BASIC , Fifth 
Ed i tion , published in 1970 by the Kiewit Computation Center/ 
Dartmouth College/ in Hanover/ New Hampshire. 

The following is a list of differences between the Dartmouth 
and Multics implementations of BASIC: 
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1) The Multics storage system conventions differ from those 
at Dartmouth. Therefore/ if a user refers to a segment 
as 

20 file #l:"a1pha" 

Multics will search for a segment named alpha in the 
user's working directory. If alpha is not found, the 
directory is searched for alpha. basic. If this is not 
found, the segment alpha is created. 

2) The number sign (#) must be entered with an escape 
character preceding it to avoid the Multics 
interpretation as an erase character. The upward arrow 
character is entered as a circumflex on Multics. 



The current version of the BASIC compiler is 
a proprietary program of Dartmouth College. 
It has been made available to users of the 
M.l.T. Information Processing Center with the 
permission of Dartmouth College. The BASIC 
compiler may not be used at other computer 
installations without permission of Dartmouth 
Col lege. 
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Command 
Development System 
9/27/71 



Name : wal k_subtree, ws 



The wal k__subtree command is used to execute a given command 
line in a given directory (called the starting node) and in all 
directories inferior to the starting node. The pathname of every 
directory in which the command line is executed is printed onto 
the user's console. Control arguments are provided to modify the 
behavior of the command (see the list below). 



Usage 

walk_subtree pathname "command line" -option!.- ... -optionQ- 



1) pathname 



is the starting node. This must be the 
first argument. If it is -wd / the 
working directory is assumed. 



2 ) "command 1 i ne" 



3) optionl 



is the command line to be executed. 
Note that the entire command line is 
taken to be a single argument. 
Therefore/ a multiple word command line 
should be typed as a quoted string. 

is chosen from the following list of 

options. These control arguments can 

appear in any order following the 
command 1 ine . 



-first Ji/ "ft a makes n the first level in the file 

system hierarchy at which the command 
line is to be executed where/ by 
definition, the starting node is level 
1. The defaul t is -f i rst 1. 

-last n/ "It n makes n the lowest level in the file 

system hierarchy at which the command 
line is to be executed. The default is 
-last 99939, i.e., all levels. 



-brief, -bf 



suppresses the printing of the names of 
the directories in which the command 
line is executed. (This is not a 
default option.) 



-bottom_up, -bu causes execution of the command line to 

commence at the last level and to 
proceed upwards through the file system 
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hierarchy until the first level is 
reached. In the default mode, execution 
begins at the highest (first) level and 
proceeds downward towards the lowest 
( 1 ast ) 1 evel . 



Notes 



The walk_subtree command establishes a program__i nter rupt 
handler. If the user quits out of the walk_subtree command and 
immediately types pi (or program_i n ter rupt ) , his working 
directory will be changed to the directory he was in when the 
wal k_sub tree command was typed. 

Examples 

Assume the following directory structure: 




Assume that the user currently has working directory Isaac 
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1) walk_subtree >udd>pr > i saac "list * . 1 i st" 

will list all the segments with a second component of "list" 
in the directory isaac and all of its subdirectories. 

2) walk_subtree >udd>pr> i saac "list * . 1 1st; dl *.list" 

will list and then delete all the segments with a second 
component name of "list" in the directory isaac and all of its 
subdi rector i es . 

3) walk_subtree -wd "list *.list" -first 3 

executes the command line "list *.list" in the directories 
john / bill, dddl, d2, d3. 

k) walk_subtree >udd>pr > i saac "list *.list" -last 2 

executes the command line "list *.list" in the directories 
isaac, fred, harry, dl. 

5) walk_subtree >udd>pr > i saac "list *.list" -last h -first 3 

executes the command line "list *.list" in the directories 
john, bill, dddl, d2. 

6) wal k__subtree fred "setacl -wd rewa isaac.pr.*" 

executes the given command line first in the directory fred, 
then in john and in bill, then in d2, and then in d3. 

7) wal k__subtree fred "deleteacl -wd isaac" -bottom_up 

executes the given command line first in the directory d3, 

then in d2, then in john and in bill, and then in fred. Note 

that the -bottom_up option is essential in this case for the 
deleteacl command to succeed. 
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Command 
2/13/73 



Name ; where/ wh 

The where command searches for a given reference name using 
the standard search rules and Initiates the segment if found. It 
prints out the full path name of that segment/ including its 
primary name. If the segment is not in the search path/ an 
error message Is printed. The segment will remain known to the 
process after the where command is invoked. 

Usage 

where namel name2 ••• namen 
1) namei is a segment reference name of <. 32 characters. 

Note 

The primary name of a segment is the name which is first in 
the list of names on a storage system directory entry. 
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Command 

Standard Service System 

8/21/72 



Name : who 



The who command determines the number/ identification and 
partial status of all users of the system. The command prints 
out a header and lists the name and project of each user. The 
header consists of the system name, the total number of users/ 
the current system load/ and the maximum load. (See the MPM 
write-up for how_many_users to print only the header.) 



Us ag e 

who -control__argl- ... -control_argn- -argl- ... -argn- 

1) cont ro l_argj_ may be chosen from the following list of 

control arguments: 

-long/ -lg prints the date and time logged in, the 
terminal identification and the load units of 
each user/ in addition to his name and 
project. The header includes installation 
identification/ the time the system was 
brought up/ and load information on absentee 
users . 

-project/ -pj sorts the output by the project 
identification of each user. 



-name, -nm sorts the output by the name of each user, 

-absentee/ -as lists only absentee users, 

-brief/ -bf suppresses the printing of the header. 

2) argi may be selected from the following list: 

Name lists only users with person name "Name". 



.Proj lists only users with project identification 

"Proj". 

Name. Proj lists only users with person name "Name" and 

project identification "Proj". 
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Notes 

Absentee users are denoted by an asterisk (*) following 
"Name. Pro j". 

Up to twenty classes of selected users are permitted. 

If the options -project or -name are omitted, the output is 
sorted on login time. 

If an argi is specified/ the header is suppressed even if 
the -long control argument is specified. The -long control 
argument will produce long information for each user listed. 

Examples 

1) Print default information, 
who 

Multics 17.6b, load 6.0/50.0; 5 users 
Absentee users = 1/2 

Backup . SysDaemon 
1 0. SysDaemon 
Jones . Facul ty 
Doe. Work 
Smi th. Student* 

2) Print long information for absentee users on the Student 
project (with no header). 

who -absentee -long .Student 

Absentee users = 1/2 

08/21/72 0050.2 none 1.0 Smi th. Student* 

3) Print brief information for all users. 

who -brief 

Backup. SysDaemon 
1 0. SysDaemon 
Jones. Facul ty 
Doe .Work 
Smi th. Student* 
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SUB R OUT IN ES 

This section contains/ in alphabetic order/ descriptions of 
all standard Multics subroutine calls. The user of this section 
will also want to refer to the Reference Guide section on the 
Multics Programming Environment/ which contains a guide to the 
subroutines, organized by function. 

The following conventions are used in subroutine 
descr i pti ons : 

1. An entry declaration/ suitable for verbatim copying 
into a calling program/ is provided. Using such a 
declaration is recommended practice/ since it helps 
reduce errors. 

2. Calling sequences are normally given for the PL/ I 
language. Users of other languages should translate 
the sequences accordingly. 

3. Following the description of each argument/ the 
notation (Input) or (Output) indicates that the 
argument is passed to or comes from the subroutine/ 
respect i vel y . 

k. I/O System Interface Modules are also alphabetically 
included in this section. 

Note that subroutines can be distinguished from commands by 
name; generally/ subroutines have names which end with a 
trailing underscore. 

Subroutines not described in this section may possibly be 
listed in the Reference Guide sections on Obsolete Procedures or 
Internal Interfaces. 
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Subroutine Call 
7/5/73 



Name : act i ve_f nc__err_ 

The act i ve_f nc_err_ subroutine is called by active functions 
when they detect unusual status conditions. It formats an error 
message (as described below) and then signals the condition 
act i ve_f unct ion_error . The default handler for this condition 
prints the error message and then returns the user to command 
level. (See the MPM Reference Guide sections. Error Handling/ 
and List of System Conditions and Default Handlers, for further 
i nformat ion. ) 

Since this subroutine can be called with a varying number of 
arguments, it is not permissible to include a parameter attribute 
list in its declaration. 

Usage 

declare act i ve__fnc_err_ entry options (variable); 

call acti ve_fnc_err_ (code, caller, control_str i ng, 
argl, argn); 

1) code is the status code (fixed bin(35)) detected. 

(Input) 

2) caller is the name (char (*) ) of the procedure calling 

act i ve__f nc_err__. It can be either fixed or 
varying. (Input) 

The remaining arguments are optional, as explained in Notes 
be 1 ow . 

3) control__str i ng is an ioa_ control string (char(*)). See the 

MPM write-up for the ioa_ subroutine. (Input) 

**) argi is an ioa_ format argument. See the MPM 

write-up for the ioa_ subroutine. (Input) 

Notes 

The error message prepared by act i ve__f nc_err_ has the format 
"caller: system__message user_message". The system message is a 
particular message from error_table_ corresponding to the value 
of code. If code = 0, no system message is included. The user 
message is constructed by ioa_ from the control string and format 
arguments. If no control_st r i ng and format arguments are given, 
the user message is omitted. 
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Development System 
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Name: adj us t_b i t_ count_ 



This procedure performs the basic work of the 

adj ust_b i t_count command. This entry is called to find the last 

nonzero word or character of a segment and set the bit count 
accord i ngl y . 



Usage 



declare adj us t_b i t_count_ entry (char(168) aligned, 

char(32) aligned, bit(l) aligned, fixed bin(24), 
fixed bin); 

call adj us t_b i t_count_ (dn, en, char_sw, bit__count, 
code) ; 



1) dn 

2) en 

3) char_sw 
k) bit count 



5) code 



is the directory pathname. (Input) 

is the entry in the directory. (Input) 

is n 0 H b if adjustment is to be made to the last 
nonzero word; it is "l n b if to the last nonzero 
character. (Input) 

is the computed bit count for the segment. If 
the value is < 0, no attempt at computing the 
count was made (code will be nonzero). If the 
value is >= 0, the computed value is correct, 
regardless of whether the bit count could be 
set. (Output) 

is 0 if the operation was successful. Any file 
system error code may be returned. (Output) 
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I/O System Interface Module 
Development System 
10/8/71 



Name : broadcasts 

The broadcast^ interface module/ or broadcaster, is one 
means by which I/O system calls may fan out, i.e., a single I/O 
system call on a single stream can result in I/O operations being 
performed on several different devices. The broadcaster permits 
a single stream to be simultaneously attached to several other 
streams. Certain I/O system calls then issued to the first 
stream will result in similar calls to each of the object 
streams. 

Note: Due to current limitations in the specifications of the 
I/O system, certain deficiencies exist in this release of the 
broadcaster. These deficiencies have to do with return 
arguments. The broadcaster performs I/O calls on several I/O 
streams and receives return values from each of these calls, 
e.g., status. However, the broadcaster itself has no way to 
return all of these return values to its caller. Currently, the 
broadcaster performs some mapping of these various values to 
determine the single value to be returned, and these mappings are 
indicated later in this document. 



Usage 



call ios_$attach (stream, "broadcas t_", obj ect_stream_, "", 
status) ; 

call ios_$attach (stream, "broadcasts", object_stream_, "", 
status); 



call ios_$attach (stream, "broadcas t_", obj ect_st reamn./ ,llf , 
status) ; 

For each object stream to be associated with the primary 
stream, an attach call, as indicated above, must be issued. All 
the various object streams will be simultaneously associated with 
the primary stream until detach calls are issued. Any I/O system 
calls listed below issued to the primary stream, except the 
attach and detach calls, will result in equivalent calls to each 
of the object streams. 
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j /0 System Calls 

The following I/O system calls are implemented by the 
broadcaster: 

abort 
attach 
detach 
resetwr i te 
wr i te 

The number of elements written/ as returned by the write 
call/ is the minimum of the number of elements written by each 
write call to an object stream. 

Device Identification 

Since the pseudo-device of the broadcast_ interface module 
is an object stream/ any stream name is a permitted device 
identification. The object stream does not have to exist at 
attach time. However/ any attempt to use a stream which 
broadcasts to a nonexistent object stream will result in an error 
status being returned. 

Status 

If any of the error codes in the status strings returned in 
I/O calls by the broadcaster to the object streams are nonzero, 
then one of these nonzero codes will be returned by the 
broadcaster. Otherwise/ the error code portion of "status" 
returned by the broadcaster will be zero. 

Modes 

The broadcaster has no modes of its own; therefore I/O 
operations performed by the broadcaster on its object streams 
take on the modes of the individual streams. 

Fl ement S i ze 

The broadcaster pays no attention to element size; therefore 
each object stream uses its own element size. Users must be 
careful that all object streams of a given broadcast stream have 
the same element size. 

Synchronization 

The broadcaster takes on the synchronization of its object 
streams. If all its object streams are write synchronous/ the 
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broadcaster will also be write synchronous. If any of the object 
streams are in write asynchronous mode, then the broadcast stream 
will be in write asynchronous mode. 

Detachment 

The caller may specify that one or all of the object streams 

be detached. If the second argument to detach is a null string/ 

all the object streams will be detached. If a particular object 

stream is specified as the second argument in the call to detach/ 
only this stream will be detached. If a call to detach leaves no 

object stream associated with the primary stream/ the primary 
stream will be deleted. 
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Subrout i ne Call 
Standard Service System 
02/16/71 



Name : change_ wdir_ 

The change_wdir_ subroutine changes the user's current 
working directory to the directory specified as its first 
argument. 

Usage 

declare change_wdir_ entry (char(168) aligned/ fixed bin); 
call change_wdi r_ (di rector y_ name, code); 

1) di rectory_name is the pathname of the directory which will 

become the user's working directory. 
(Input) 

2) code is a standard file system error code. See 

the MPM Reference Guide Section on 

"Miscellaneous Reference Data". (Output) 



(END) 



MULT ICS PROGRAMMERS 1 MANUAL 



ch e c k_s t a r _n ame_ 



Subroutine Call 
9/28/73 



Name ; check_star_name_ 



This procedure validates an entry name to insure that is has 
been formed according to the rules for constructing star names. 
These rules are given in the MPM Reference Guide section. 
Constructing and Interpreting Names. It also returns a status 
code that indicates whether the entry name contains asterisks or 
question marks, and whether it is a star name that matches every 
entry name. 



Entry ; check_star_name_$path 



This entry point accepts an absolute path name as its input. 
It validates the final entry name in that path, as described 
above. 



Usage 



declare check_star_name_$path entry (char(*), 
fixed bin(35)); 



call check_star__name_$path (pathname, code); 



1) pathname is the absolute path name whose final entry name 

is to be validated. Trailing spaces in the path 
name character string are ignored. (Input) 

2) code is one of the following status codes: (Output) 

0 the entry name is valid, and does not contain 
stars or question marks. 

1 the entry name is valid, and does contain stars or 
question marks. 

2 the entry name is valid, and is a star name that 
matches every entry name. This means that the 
entry name is either M ** M , or "*.**", or "**.* n . 



er ror__tabl e__$ bads tar 

the entry name is invalid. It violates one or 
more of the rules for constructing star names. 
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En try ; check__star__name_$ent ry 

This entry point accepts/ as input/ the entry name to be 
val i dated. 

Usage 

declare check_star_name_$entry entry (char(*)/ 
fixed bin(35)); 

call check_star__name__$entry (entryname/ code); 

1) entryname is the entry name to be validated. Trailing 

spaces in the entry name character string are 
ignored. (Input) 

2) code is as above. (Output) 

Notes 

Refer to the MPM write-up for the hcs_$star__ subroutine to 
see how to get a list of directory entries that match a given 
star name. 

Refer to the MPM write-up for the match_star_name_ 
subroutine to see how to compare an entry name with a given star 
name. 
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Name : clock_ 

The clock_ procedure reads the system clock. The time 
returned is a fixed bin(71) number equal to the number of 
microseconds since January 1/ 1901/ 0000 hrs GMT. It is suitable 
for input to the date_ time_ subroutine which converts the time to 
an ASCII representation. 

Usage 

declare clocks entry returns (fixed bin(7D); 
date_time = clock_ (); 

1) date_time is the number of microseconds since January 1/ 
1901/ 0000 hrs GMT. (Output) 

Note 

Since the "leap second" declared by the National Bureau of 
Standards on June 30/ 1972/ the value returned by clock_ 
understates the time since January 1/ 1901/ 0000 hrs GMT by one 
second. As a result/ conversion routines which ignore the "leap 
second" will give correct answers for times since midnight of 
June 30/ 1972, and will be one second high for times before that 
date. 
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Name : com_e r r_ 



This is the principal error message printing subroutine. It 
should be called to report any unusual status condition/ e.g., 
when a nonzero status code is returned. 

Since this procedure can be called with a different number 
of arguments, it is not permissible to include a parameter 
attribute list in the declaration. 

See also the MPM Reference Guide section, Strategies for 
Handling Unusual Occurrences. 

Entry: com_er r_ 

This procedure formats an error message (as described below) 
and then signals the condition commands, error . The default 
handler for this condition simply returns control to com_err_ 
which then writes the error message on the stream "er ror_ output" . 

Vsafie 

declare com_err_ entry options (variable); 

call com__err_ (code, caller, control_s tr i ng, argj. ... argn); 

1) code is a status code (fixed bin (35)) as returned 

from system entry points, etc. If code = 0, 
no system message is printed. (Input) 

2) caller is the name of the procedure ( character (*) ) 

calling com_err . It may be either fixed or 
varying. (Input; 

The remaining arguments are optional, as explained in the Notes 
below. 

3) con trol_str i ng is an ioa_ control string (character (*)) . See 

the MPM description of ioa_. (Input) 

k) argX is an ioa_ format argument. See the MPM 

description of ioa_. (Input) 

Notes 

The error message prepared by com_err_ has the format 
"caller: sys tem_message user_message" . The system message is a 
particular message from error__tab le_ corresponding to the value 
of code. If code = 0, no system message is included. The user 
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mgccggg js constructed by i 03 from the control string and format 

arguments. If no control__str i ng or format arguments are given/ 
the user message is omitted. 

Fntry : com_er r_$suppress_name 

This is the recommended entry to use when the caller name 
and colon are not wanted because it still allows a meaningful 
caller name to be passed to the command_error condition handler. 
Otherwise/ it is the same as the com__err_ entry. 

Usage 

declare com_er r_$suppress_name entry options (variable); 

call com_err_$suppress__name (code/ caller/ control__str i ng/ 
argl . . . argn) ; 

The description of the arguments is the same as for 
com_err_. The argument "caller 11 must not be null or blank 
because condition handlers for command_er ror need to know who 
s i gnal 1 ed them. 

Notes 

If a nonzero code is provided which does not correspond to an 
er ror_tab 1 e_ entry/ the system message will be of the form 
"Code ddd not found in er ror_tab 1 e__"/ where ddd is the decimal 
respresentat ion of code; if code is negative the message will be 
of the form "I/O Status 000 " where 000 is the 12-digit unsigned 
octal representation of code (this form is intended for use by 
I/O System device interface modules (DIMs) which wish to return 
hardware error status to their callers; the actual interpretation 
of the value is dependent on the physical device and the 
individual DIM). 
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Name : comma nd_quer y_ 

This subroutine is the standard system procedure invoked to 
ask a question and obtain an answer from the user. It formats 
the question (as described below) and then signals the condition 
command__quest ion . See the MPM Reference Guide section. List of 
System Conditions and Default Handlers. The default handler for 
this condition simply returns control to comma nd_query_ which 
writes the question on the stream user_i/o. It then reads the 
stream user_input to obtain the answer. Several options have 
been included in command_query_ to support the use of a more 
sophisticated handler for the command_quest ion condition. 

Since this procedure can be called with different numbers of 
arguments, it is not permissible to include a parameter attribute 
list in the declaration. 

Usage 

declare command^ query_ entry options (variable); 

call command_query_ (p, answer, caller, cont rol_str ing, 
argJL ... argn.); 

Dp is a pointer to the structure 

below. ( Input) 

declare 1 query_info aligned, 

2 version fixed bin init(2), 

2 yes_or_no_sw bit(l) unaligned, 

2 suppress_name__sw bit(l) unaligned, 

2 status_ code fixed bin(35), 

2 query_code fixed bin(35); 

(1) version is the version number of this 

structure. (Input) 

(2) yes_or_no_sw if "l"b, comma nd_query_ will not 

return until a yes or no answer is 
read. (Input) 

(3) suppress_name__sw if "l"b, the name of the calling 

procedure will be omitted from the 
question. See Notes below. 
( I nput ) 



© 
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(4) s»tdtU3__COde 



(5) query_code 



is the status code which prompted 
the question; otherwise it should 
be zero. ( I nput ) 



is currently 
intended for 
handlers for 
( Input) 



ignored. It is 
use by special ized 
command_quest ion . 



2) answer 



is the response ( character ( *) 
varying) read from user_input. 
Leading and trailing blanks plus 
the "new 1 ine" character have been 
removed. (Output) 



3) caller 



is the name (character (*) ) of the 

I t may be 
nonvary ing. 



cal 1 i ng 
either 
( Input) 



procedure . 
varying or 



The remaining arguments are optional as explained in the Notes . 



h) control_str ing 



5) argl 



is an ioa_ 
(character ( *) ) 
description of 



control string 
See the MPM 
oa__. (Input) 



1 s an 10a 
the MPM 
( Input) 



format argument. See 
description of ioa_. 



Notes 



The question prepared by comma nd_query_ has the format 
"caller: message". If suppress_name_sw is on, then the caller 
name will be omitted from the question. The message is 
constructed by ioa_ from the control string and format arguments. 
If no control string and therefore no format arguments are given, 
the message portion of the question is omitted. 
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Name : condition. 

This procedure establishes a handler for a condition in the 
calling block activation. If a handler for the specified 
condition is currently established in the calling block 
activation, it will be overridden. 

A description of the condition mechanism is given in the MPM 
Reference Guide section on The Multics Condition Mechanism. 

Usage 

declare condition_ entry (char(*), entry); 
call condition,, (name, handler); 

1) name is the name of the condition for which the handler 

is to be established. (Input) 

2) handler is the handler to be invoked when the condition is 

ra i sed . ( I nput ) 

Notes 

The condition names unci a imed_s i gnal and cleanup are 
obsolete special condition names and should not be used. 

The PL/ I on statement and the condition, subroutine must not 
be invoked during the same block activation in order to establish 
a handler for the same condition. 

In order to explicitly revert a handler established by a 
call to condition., the reversion, (see the MPM subroutine) 
procedure must be called. The PL/ I revert statement must not be 
used for this purpose. 

In PL/ I Version 2, when a call to condition, appears within 
the scope of a begin block or internal procedure of a procedure, 
the no.quick.b locks option must be specified in the procedure 
statement of that procedure. The no.qu i ck.bl ocks option is a 
nonstandard feature of the Multics PL/ 1 language and, therefore, 
programs using it may not be transferable to other systems. 
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Name : convert_b i nary__i nteger_ 

This procedure performs conversion from binary integers to a 
character string representation either in the octal base or the 
decimal base. It contains entries to handle double precision 
i ntegers . 

The string representation is returned as an appropriate 
varying character string with no included blanks and an assumed 
decimal (binary) point at the right. If the argument is 
negative, the first character of the returned value will be a 
minus sign. Leading zeros will be omitted. 

Entry : convert_b inary_i nteger_$dec i ma1_str i ng 

This entry converts a single precision binary integer to its 
decimal string representation. 



Usage 



declare convert_binary_integer_$decimal_string entry 
(fixed bin(35)) returns (char(12) varying); 



string 55 convert_binary_ = integer_$decimal_str ing (number); 

1) number is a binary integer to be converted. (Input) 

2) string is the representation of "number" in the decimal 

base. (Output) 

Entrv : convert_b i nary_i nteger_$octal_st r i ng 

This entry converts a single precision binary integer to its 
octal string representation. 



Usage 



declare convert_binary_integer_$octal__str i ng entry 
(fixed bin(35)) returns (char(13) varying); 



string = convert_b i nary_i nteger_$octal_st r i ng (number); 

1) number is a binary integer to be converted. (Input) 

2) string is the representation of "number" in the octal 

base. (Output) 
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Fnt rv : convert__b inary_i nteger $long dec i mal__s t r ! ng 

This entry converts a double precision binary integer to its 
decimal string representation. 

Usage 

declare convert_binary_jnteger_$long_decimal__str ing entry 
(fixed b!n(7D) returns (char(23) varying); 

string = convert_binary_integer_$long_decimal__str ing 
( long_num) ; 

1) long__num is a double precision binary integer to be 

converted. ( Input ) 

2) string is the representation of long__num in the decimal 

base. (Output) 

Fntrv : convert_b i nary__i nteger_$ long_pctal_st r i ng 

This entry converts a double precision binary integer to its 
octal string representation. 

Usage 

declare convert_binary_integer_$1ong_octal_str ing entry 
(fixed bin(7D) returns (char(25) varying); 

string = convert binary integer, $ long^ octal , str i ng 

( long_num) ; 

1) long_num is a double precision binary integer to be 

converted. (Input) 

2) string is the representation of long_num in the octal 

base. (Output) 



(c) Copyright/ 
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Name : convert_date__to_b i nary_ 

The convert_date_to_bi nary_ subroutine converts a character 
representation of a date and time into the 72-bit system clock 
format. It accepts a wide variety of date and time forms, 
including the output of date_time_ (see the data_time_ subroutine 
write-up in the MPM). 

Usage 

declare convert_date_to_bi nary_ entry (char(*), 
fixed bin(71) / fixed bin(35)); 

call convert_date_to__bi nary__ (string, clock, code); 

1) string is the character representation of the clock 

reading desired. It has up to five parts 
(date, time, day-of-week, offset, and time 
zone), all of which are optional. They may 
appear only once and in any order. If all of 
them are omitted, the current time is 
returned. Each part can be made up of 
alphabetic fields, numeric fields, and 
special characters. An alphabetic field is 
made up of letters. The whole word or an 
abbreviation made up of the first three 
letters must be supplied. That means that 
Jan and January are equivalent. No 
distinction is made between upper and lower 
case. A numeric field consists of an integer 
of one or more decimal places. In addition, 
there are four special characters: the slash 
(/); the period (.); the colon (:); and the 
comma (,). Blanks are necessary to separate 
two numeric fields or two alphabetic fields. 
They are optional between alphabetic and 
numeric fields. 

The five parts of the clock reading are: 

date This is the date of the year. The year is 

optional, and, if omitted, is assumed to be 
the year in which the date will occur next. 
That is, if today is March 16, 1971, then 
March 20 is equivalent to March 20, 1971, 
while March 12 is the same as March 12, 1972. 
There are three forms of the date, 
illustrated by the examples below: 
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16 March 1971 or 16 March 

March 16, 1971 or March 16 1971 or March 16 
(Note that the comma is optional.) 

3/16/71 or 3/16 

time This is the time of day. If omitted, it is 

assumed to be the current time. It has two 
basic formats, 24-hour and meridional time. 
The 24-hour time format consists of a four 
digit number hhmm, where hh is the hour, and 
mm is the minutes, followed by a period, and 
an optional decimal fraction of a minute 
field. Also acceptable are hours, minutes, 
and an optional seconds field separated by 
colons. The minutes and seconds fields must 
be two digits in length each. 

Examples of 24-hour time are: 

1545. 

1545.715 

15:45:08 

Meridional time must end with a meridional 
designator (i.e., am, pm, noon (or n), 
midnight (or m)). If it is not preceded by a 
time, midnight (0000.0) is indicated by the 
alphabetic fields m or midnight, and noon 
(1200.0) is indicated by n or noon. The 
designator may be preceded by an hour, an 
hour-colon-minutes time, or an 

hour-colon-minutes-colon-seconds time. The 
minutes and seconds fields, if present, must 
be two digits in length. 

Examples of meridional time are: 

mi dni ght 

5 am 

5:45 am 

11:07:30 pm 
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day-of-week This field Is the day of the week (i.e., 
Monday, Tuesday, etc.). If the day of the 
week is present along with a date, the date 
must fall on that day of the week or else a 
status code is returned. If a date is not 
present, the first day of the week after the 
current date is used; that means that Tuesday 
is interpreted as next Tuesday. 

offset This field specifies an amount of time to be 

added to the clock value specified by the 
other fields. Offsets may be specified in 
any and all of the following units: 

seconds (second, sec) 

minutes (minute, min) 

hours (hour) 

days (day) 

weeks (week) 

months (month) 



Only one occurrence of each unit can be 
present, each preceded by an integer. The 
singular version can only be used with 1, the 
plural for any other value. Note that if the 
offset field is the only field present, the 
offset is added to the current time. 

If the month offset results in a nonexistent 
date (e.g., "Jan 31 3 months" would yield 
April 31), the last date of the resulting 
month is used (e.g., April 30). The month 
offset is applied before the other offsets 
and must not be abbreviated nor used with the 
zone field. 



Examples of offset fields: 



1 hour 5 minutes (an hour and five minutes 
from now) 

Monday 6 am 2 weeks (two weeks from next 
Monday) 
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zone This is the starting time zone to be used in 

making the conversion to GMT. It currently 
may be any of the following: 

GMT (Greenwich mean time) 

EST (eastern standard time) 

EDT (eastern daylight time) 

CST (central standard time) 

CDT (central daylight time) 

MST (mountain standard time) 

MDT (mountain daylight time) 

PST (Pacific standard time) 

PDT (Pacific daylight time) 

or the current time zone used by the system. 

If omitted / the current time zone used by the 
system is assumed. 

Note that if the date and day of the week are 
not present/ the time returned is the next 
instance of that time after (or equal to) the 
current time. For example, if it is 
currently 3 pm, April 15, then 2 pm means 2 
pm on the 16th, while 7 pm means 7 pm on the 
15th (i.e., tonight). 

2) clock is set by conver t_date_to_b i nary_ to the 

computed clock value. It is returned 
unchanged in the event of an error. 

3) code is a standard Multics status code. 

either zero (no errors), 

er ror_tabl e_$date_convers i on_er ror . 
nonzero value is returned in all 
fol lowi ng cases: 

1) General syntax error. 

2) Unrecognized alphabetic field. 

3) Two or more dates, times, etc. 
k) Month without a date number. 

5) Year not in the twentieth century. 

6) Date of month does not exist (e.g., 
35 March). 

7) Midnight and noon preceded by an 
hour other than 12. 

8) Minutes greater than 59. 

9) Seconds greater than 59. 

10) 2i*-hour time after 2^00.0 specified. 

11) Zero hours in meridional time. 
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Ik) 
15) 
16) 



12) 
13) 



17) 



Month greater than 12 in slash time. 

Minutes or seconds not two decimal 

places in length. 

Day of week and date conflict. 

Improper use of comma. 

24-hour time less than three places 

in length. 

Improper use of offset. 



Entry ; conver t_da te__to__b i nary_$ rel at i ve 

This entry is similar to convert_date_to_binary__, except 
that the clock reading returned is computed relative to an input 
clock time rather than the current clock time. Thus the clock 
reading returned for the string "March 26" is the clock reading 
for the first March 26 following the input clock time, rather 
than the clock reading for the first March 26 following the 
present clock time. Given a 72-bit clock time to use, this entry 
converts a character representation of a date and time to the 
equivalent 72-bit system clock representation. 

declare conver t_date_to__bi nary__$ rel at i ve entry 
(char(*), fixed bin(71), fixed bin(71), 
fixed bin(35)); 

call conve rt_da te_to_bi nary_$rel at i ve (string, clock, 



clock_in, code); 



1) string 



is as above. (Input) 



2) clock 



is the clock time determined by string relative to 
clock__in. (Output) 



3) clock__in 



is the clock time relative to which string is 
converted into a clock time. (Input) 



4) code 



is as above. (Output) 



Examples o_£ Input 



March 23 



17 May 1974 EST 8:30 pm 



03/28/71 2252.9 EST Sun 
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Entrv : copy_acl_ 

This procedure copies the access control list from one 
segment to another. The ACL on the target segment is emptied 
before the new list is added. 

Usage 

declare copy_acl_ entry (char(*), char(*), chart*), 
char(*), char(*), bit(l) aligned, fixed bin(17)); 

call copy_acl_ (dirl, enl, dir2, en2, errsw, code); 

1) dirl is the directory in which the original segment is 

found. ( I nput ) 

?.) enl is a name on the original segment. (Input) 

3) dlr2 is the directory in which the target segment is 

found. (Input) 

k) en2 is a name already on the target segment. (Input) 

5) errsw indicates whether the error indicated by "code 11 

occurred on the original segment ( !l 0 f, b) or on the 
target segment ("l"b). (Output) 

6) code is a standard file system error code. (Output) 



(END) 
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Name ; copy_names_ 

This procedure copies all the names from one segment to 
another. Name duplications are handled by the standard system 
name duplication handling procedure. 



"sage 

declare copy_names_ entry (char(*), char(*) / char(*), 
char(*) / char(*), bit(l) aligned / fixed bin); 

call copy_names_ (dirl, enl, dir2 / en2, caller, errsw, 
code ); 

1) dirl is the absolute path name of the directory in which 

the original segment is found. (input) 

2) enl is a name on the original segment. (Input) 

3) dir2 is the absolute path name of the target segment's 

directory. (Input) 

k) en2 is a name already on the target segment. (Input) 

5) caller is the name of the calling procedure. It is used by 

the standard system name duplication handling 
procedure. (Input) 

6) errsw indicates which segment the error indicated by the 

code argument occurred in. It is "0"b if the error 

was on the original segment and "l"b if on the 
target segment. (Output) 

7) code is a standard storage system status code. (Output) 
qote 

If a name duplication occurs due to another segment having 
the same name as the one copied, the status code 
error_table__$namedup is returned. Otherwise/ if a name 
duplication occurs due to name being copied into a segment having 
the same name, the status code er ror_tabl e__$segnamedup is 
returned. 
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Name : copy_seg_ 

This procedure produces a copy of a Multics nondi rectory 
segment. The new segment is created with rewa access for the 
creator. 

declare copy_seg_ entry (char(*), char(*), char(*), 

char(*), char(*), bit(l) aligned, fixed bin); 

call copy_seg_ (dlrl, enl, dir2, en2, caller / 
errsw, code); 

1) dirl is the absolute path name of the directory in which 

the original segment is to be found. (Input) 

2) enl is a name on the original segment. (Input) 

3) dir2 is the absolute path name of the directory In which 

the copy is to be created. (Input) 

k) en2 is the name to be given the new segment. (Input) 

5) caller is the name of the calling procedure. It is the 

procedure name that will be printed in status 
messages and questions. (Input) 

6) errsw indicates which segment the error reported via the 

code argument occurred in. It is "0 n b if the error 
was on the original segment and "l"b if on the 
target segment. (Output) 

7) code is a standard system status code. (Output) 
Notes 

The following status codes may be of special interest to the 
caller of copy_ seg_: 

error_ table_$d Irseg 
error__tabl e__$moderr 
er ror_ tab 1 e_$namedup 
er ror_tab 1 e_$ sameseg 

Note that other status codes may also be returned. 
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Entry : co py_se g^_$ no_me s s ag e 

This entry point performs the same task as copy_seg_ with 
the exception that the messages "Bit count inconsistent with 
current length... 11 and "Current length is not the same as 
records used..." are suppressed. 

Usage 

declare copy_seg_$no_message entry (char(*)/ char(*), char(*) 
char(*), char(*), bit(l) aligned, fixed bin); 

call copy_seg^.$no — message (dirl, enl, dir2, en2, 
caller, errsw, code); 

Same arguments as above. 
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Name : cpu_t ime_and__pagi ng_ 

This procedure returns the total CPU time used by the 
calling process since it was created as well as two measures of 
the paging activity of the process. 

usage 

declare cpu_t ime__and_paging_ entry (fixed bin, fixed bin(71)/ 
fixed bin); 

call cpu_ time_and_paging_ (pf / time, pp); 

1) pf is the total number of page faults taken by the calling 

process. (Output) 

2) time is the total cpu time used by the calling process. 

(Output) 

3) pp is the total number of pre-pagings for the calling 

process. (Output) 
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Name : cu_ 

The cu_ (command utility) module provides several short 
subroutines coded in machine language which provide functions not 
directly available in the PL/ I language. Although these 
subroutines are designed primarily for the use of command 
writers, many may prove useful to Multics users and subsystem 
developers. 

pntrv : cu_$arg_count 

The arg_count entry may be used by any procedure to 
determine the number of arguments with which it was called. 

Usage 

declare cu__$arg_count entry (fixed bin); 

call cu_$arg_count (nargs); 

1) nargs is the number of arguments passed to the 

caller of arg_count by his caller. (Output) 

Entry: cu_$arg_ptr 

The arg_ptr entry is designed for use by a command or 
subroutine which is callable with a varying number of arguments/ 
each of which is an adjustable length unaligned character string 
(i.e./ declared char(*)). This entry returns a pointer to and 
the length of a specified character string argument. 

The command or subroutine which uses this entry must be 
called with data descriptors for its arguments. Otherwise/ the 
returned value of arglen will be zero. If the argument specified 
by argno is not a character string/ arglen will be the value of 
the "size" field of the descriptor (the rightmost 18 bits for old 
descriptors, the rightmost 2k bits for new descriptors). This 
entry must not be called from an internal procedure which has its 
own stack frame (because arg_ptr does not check for a display 
pointer). 

Usage 

declare cu_$arg_ ptr entry (fixed bin, pto fixed bin/ 
fixed bin(35)>; 

call cu_$arg__ptr (argno, argptr, arglen/ code); 
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1; 
2) 
3) 
h) 



argno 
argptr 
arglen 
code 



1 s an integer specifying the number of the 
desired argument. (Input) 

is a pointer to the unaligned character 
string argument specified by argno. (Output) 

is the length (in characters ). of the argument 
specified by argno. (Output) 

is an error status code. The code may be one 
of the following: 0 (normal return) or 
error__table_$noarg (the argument specified by 
argno does not exist). If error_tabl e_$noarg 
is returned, the values of argptr and arglen 
are undefined. (Output) 



Entrv : cu_$arg_pt r_re 1 

Some PL/ I procedures may wish to reference arguments passed 
to other procedures. This entry permits a procedure to reference 
arguments in any specified argument list. 

usage 

declare cu_$arg_ptr_rel entry (fixed bin, ptr, fixed bin, 
fixed bin(35), ptr); 

call cu_$arg_ptr_rel (argno, argptr, arglen, code, ap); 

1-4) are the same as for cu_$arg_ptr , 

5) ap is a pointer to the argument list from which 

this argument is being extracted. This 
pointer may be determined by calling 
cu_$arg_l i st_ptr in the program whose 
argument list is to be processed and then 
passing it to the program wanting to look at 
the argument list. (Input) 

Entrv : cu__$arg_l i st_ptr 

It is sometimes desirable to design a PL/ I procedure to 
accept a variable number of arguments of varying data types 
(e.g., ioa_). In these cases, the PL/I procedure must be able to 
interrogate its argument list directly to determine the number, 
type, and location of each argument. The arg_J i s t__ptr entry is 
designed for use in such cases and returns a PL/ 1 pointer to its 
caller's argument list. 
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usage 

declare cu__$arg_l i s t_ptr entry (ptr); 

call cu__$arg_l ist__ ptr (ap); 

1) ap is a pointer to the callers' argument list. 

(Output) 

Entry : cu_$af_arg_count 

This entry assumes it has been called by an active function. 
It returns to its caller the number of arguments passed to the 
caller by i ts caller/ not including the active function return 
argument. If the caller has not been invoked as an active 
function a status code is returned. 

Usage, 

declare cu_$af__arg_count entry (fixed bin, fixed bin(35)); 
call cu__$af_arg__count (nargs, code); 

1) nargs is the number of input arguments passed to 

the caller. (Output) 

2) code may be one of the following: 

0 - caller was called as an active function; 

error_tab le__$ nodes cr - no argument 
descriptors were passed to the caller or an 
incorrect argument list header was 
encountered; 

error_table_$not_act_f nc - the caller was not 
invoked as an active function. (Output) 

Note 

This entry and the two following entries, cu_$af_arg_ptr and 
cu_$af_return_arg, have been provided so that active functions 
need not have knowledge of the mechanism for returning arguments 
programmed into them. 
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Entrv : cu_$af_a rg_p t r 



This entry assumes it has been called by an active 
function. It operates in the same fashion as cu_$arg_ ptr, except 
that it verifies that the caller was invoked as an active 
function, and does not allow the return argument to be accessed. 
That is, if the return argument happens to be the ith argument in 
the actual argument list, and one asks cu_$af_arg_ptr for the ith 
argument, it will return the ( i +l) st argument (if any). If the 
( i +l) st argument does not exist a "no argument" status code will 
be returned. In practice, the return argument is currently 
always the last one, but use of this entry and the following 
entry allows the active function to be independent of the 
position of the return argument in the argument list. (See Note 
under cu__$af_arg_count above.) 

declare cu_$af_arg_ptr entry (fixed bin, ptr, fixed bin, 
fixed bin(35)); 

call cu__$af_arg_ptr (argno, argptr, arglen, code); 

1) argno is the number of the desired argument. 

(Input) 



2) argptr 



3) arglen 



k) code 



is the same as for cu_$arg_ptr, 
it is set to the null value if 
encountered. (Output) 



except that 
any error is 



is the same as for cu_$arg_ptr, except that 
it is set to 0 if any error is encountered. 
(Output) 

is the same as for cu_$af__arg__count, except 
that error__tab1e__$noarg may also be returned, 
meaning that the argno-th input argument was 
not present. (Output) 



Entrv : cu_$af_return_arg 



This entry assumes it has been called by an active function. 
It makes the active function's return argument available as 
described in Note below. It is provided to permit writing of 
active functions which accept an arbitrary number of arguments. 
(See Note under cu_$af_arg_count above). 
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Usage 

declare cu_$af_return_arg entry (fixed bin, ptr, fixed bin, 
fixed b!n(35)); 

declare return_str ing char (max_Jength ) varying based 
(rtn_string_ptr); 

call cu_$af_return_arg (nargs, rtn_str ing_ptr, 
max_length, code); 

1) nargs is as in cu_$af_arg_count . (Output) 

2) rtn_str ing_ptr is a pointer to the varying string return 

argument of the active function. (Output) 

3) max_length is the maximum length of the varying string 

pointed to by rtn_str ing_.pt r . (Output) 

k) code is as In cu_$af_arg_count . (Output) 

Note 

An active function which takes an arbitrary number of 
arguments makes use of this entry to return a value as follows. 
It calls the entry to get a pointer to the return argument and 
its maximum length. It declares the based varying string, 
return_str ing, as described above. It then merely assigns its 
return value to return_str ing. 

Entrv : cu__$s tack_frame_.pt r 

The stack_f rame_.pt r entry returns a pointer to its caller's 
stack frame. 

Usage 

declare cu_$stack_f rame_.pt r entry (ptr); 

call cu_$stack_f rame_ptr (sp); 

1) sp is a pointer to the caller's stack frame. 

(Output) 

Entrv ; cu_$s tack_f rame_s i ze 

The st ack_.fr ame_s i ze entry returns the size (in words) of 
its caller's stack frame. 
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Usase 

declare cu_$stack_f rame_s i ze entry (fixed bin); 

call cu_$stack_f rame_size (size); 

1) size is the size (in words) of the caller's stack 

frame. (Output) 

Entrv : cu_$gen_cal 1 

The gen_call entry is used to generate a standard call to a 
specified procedure with a specified argument list. This call is 
designed for cases in which a PL/I procedure has explicitly built 
an argument list from its input data. The principal use of this 
entry is by command processors which call a command with an 
argument list built from a command line input from a terminal. 

declare cu_$gen__cal 1 entry (ptr, ptr); 
call cu_$gen_cal 1 (proc_ptr, ap); 

1) proc_ptr is a pointer specifying the procedure entry 

point to be called. (Input) 

2) ap is a pointer to the argument list to be 

passed to the called procedure. (Input) 

Entrv : cu_$ptr_call 

The ptr_cal1 entry is used to call a procedure, the name of 
which is not known at compilation time. This entry is similar to 
gen__call with the exception that the argument list of the 
procedure to be called is known at compilation time rather than 
constructed at execution time. 

Usage 

declare cu_$ptr_call entry; 

call cu_$ptr_call (proc_ptr, argl, . .., argn); 

1) proc_ptr is a pointer to the procedure entry point to 

be called. (Input) 

2) arg_L is an argument (which may be of any type) to 

be passed to the procedure specified by 
proc_ptr. (Input) 
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Entry ; cu_$set_cp 

Some standard commands (e.g./ edm) allow the user to type 
normal command lines even when the user is not currently at 
command level. When one of these commands recognizes a command 
line, the command line is passed to the command processor for 
processing. In order to allow use of these standard commands in 
a closed subsystem environment (e.g./ Limited Service System)/ 
these commands (edm/ etc.) do not call the command processor 
directly but call the cp (command processor) entry point in cu_ 
which will pass control to the procedure entry point defined as 
the current command processor. The set_cp entry point allows a 
subsystem developer to replace the standard command processor 
with a procedure of his own. This mechanism can be used to 
insure that the subsystem remains in full control and still allow 
subsystem users the use of many standard commands. 

Usage 

declare cu__$set_cp entry (ptr); 

call cu_$set_cp (proc__ptr); 

1) proc__ptr is a pointer to the procedure entry point to 

which control is passed upon receiving a call 
to cu_$cp. (See below.) If proc_.pt r is 
null/ cu_$cp will call the standard command 
processor. (Input) 

Entry: cu_$cp 

The cp entry is called by any standard command which 
recognizes normal Multics command lines. When a Multics command 
line is recognized by one of these commands/ a call is made to 
cu_$cp to pass the command line to the currently defined command 
processor for processing. The contents of the command line are 
destroyed. 

Usagg 

declare cu_$cp entry (ptr, fixed bin/ fixed bin(35); 
call cu_$cp (line_ptr/ line_len, code); 



1) line_ptr is a pointer to the beginning of an aligned 

character string containing a command line to 
be processed. (Input) 
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2) line__len is the length of the command line in 

characters, (input) 

3) code is an error status code. If code is 

non-zero, an error has been detected in the 
command processor. However/ the caller of cp 
is not expected to print a diagnostic at this 
time since it can be expected that the 
command processor has already done so. 
(Output) 

Entrv: cu_$get_cp 

This entry returns to the caller a pointer to the procedure 
currently being invoked in a call to cu_$cp. A null pointer is 
returned if the default standard command processor is being 
invoked by cu_$cp. 

Usage, 

declare cu_$get__cp entry (ptr); 

call eu_$ge t_cp ( proc_pt r ) ; 

1) proc_ptr is a pointer to the procedure entry point to 

which control is passed upon receiving a call 
to cu__$cp. (Output) 



Entrv : cu_$set_ cl 

The Standard Service System provides a set of procedures to 
handle any error conditions which may be signalled within a 
process (see signal_, condition^, and reversion^). The standard 
error handlers attempt to type an understandable diagnostic and 
call a procedure to reenter command level. Reentering command 
level is done for a Standard Service user via a call to 
get__to_cl_$uncl aimed__s i gnal . However/ in order to allow use of 
the standard error handling procedures in a closed subsystem 
environment/ the error handlers do not call 

ge t__to_cl__$uncl a !med_s i gnal directly but call the cl (command 
level) entry point in cu_ which will pass control to the 
procedure entry point currently defined by the last call to 
cu_$set__cl. If cu__$set_cl has never been called in the process/ 
control will be passed to get__to_cl_$uncl aimed_s i gnal on a call 
to cu_$cl. 
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Usage 

declare cu_$set__cl entry (ptr); 

call cu_$set_cl (proc_ptr); 

1) proc__ptr is a pointer to the procedure entry to be 

called by the standard error handlers after 
printing a diagnostic message. If proc_ptr 
Is null, get_to_cl_$uncl aimed_s i gnal will be 
called. (Input) 

Entrv: cu_$cl 

The cl entry is called by all standard error handlers after 
printing a diagnostic message. This entry will pass control to 
the procedure specified by the last call to set_cl. If no such 
procedure has been specified (the normal case for the Standard 
Service System), control is passed to get_to_cl_$undaimed__signal 
which reenters command level. 

Usage 

declare cu_$cl entry; 

call cu_$cl ; 

There are no arguments. 

Entry: cu_$get_ci 

This entry returns to the caller a pointer to the procedure 
entry currently being invoked by a call to cu_$cl. If a null 
pointer is returned, then the default call, to 
get__to_cl_$und aimed_s ignal , is made by cu_$cl. 

Usage 

declare cu_$get__cl entry (ptr); 

call cu_$get_cl (proc__ptr); 

1) proc_ptr is a pointer to the procedure entry being 

called by the standard error handlers after 
printing a diagnostic message. (Output) 
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Entrv : cu_$ level_.se t 

The level_set entry is used to change the current protection 
ring validation level. This entry is useful for procedures which 
must distinguish the periods of time when the procedure is acting 
in behalf of itself (i.e./ its own ring) and when it is acting in 
behalf of another procedure which may be in an inferior (i.e./ 
lower privilege) protection ring. 

Usage, 

declare cu_$ level__set entry (fixed bin); 

call cu_$level__set (level); 

1) level specifies the new protection validation level 

and must be greater than or equal to the 
current ring number. (Input) 

Entrv: cu_$ 1 evel_get 

The level_get entry is used to obtain the current ring 
validation level. This entry is normally used prior to a cali to 
level_set to save the current validation level. 

declare cu__$ level_ get entry (fixed bin); 
call cu_$leve1_get (level); 
1) level is the current validation level. (Output) 
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N9Pie: cv_acl. 



This subroutine, given a pointer to an Access Control List 
(ACL), and the array index of an entry in the ACL, formats the 
entry for printing, returning the formatted string to the caller. 
Options allow suppression of the mode, process class identifier, 
and error message subfields. Refer to the MPM Reference Guide 
section, Access Control, for a discussion of access control and 
to the subroutine writeup for hcs_$add_acl_entr ies for a 
description of an ACL structure. 

The formatted ACL entry which is returned has the form: 

rew User. Project. * error_table_ message 



Usage 



declare cv_acl_ entry (ptr, fixed bin, char(*), fixed bin, 
bit(*)); 

call cv_acl_ (acl_ptr, index, string, len, options); 



1) acl_ptr 

2) index 

3) string 

h ) len 

5) options 



is a pointer to the ACL array, one of which is to 
be formatted. (Input) 

is the array index of the ACL entry to be 
formatted. (Input) 

is the resultant formatted string containing the 
mode, process class indentifier, and error message 
as described above. (Output) 

is the number of significant characters in string. 
(Output) 

are control bits allowing suppression of various 
parts of the output: (Input) 

bit 1 on - include mode 

bit 2 on - include error_table_ message associated 

with the status code in the ACL entry 
bit 3 on - suppress process class identifier. 
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Name : cv_bin_ 

The cv_bin__ procedure converts a binary integer (of any 
base) to a twelve-character ASCII string. 

Usage 

declare cv_bin_ entry (fixed bin, char(12), fixed bin); 
call cv__bin_ (n, string, base); 

1) n is the binary integer to be converted. (Input) 

2) string is the character string in which to return the 

ASCII representation. (Output) 

3) base is the base to use in converting the binary 

integer. (e.g./ base = 10 for decimal integers). 
( Input) 

Entry ; cv_bin_$dec 

This entry converts a binary integer of base 10 to a 
twelve-character ASCI I string. 

Usage 

declare cv_bi n__$dec entry (fixed b i n, char (12)); 

call cv__bin_$dec (n, string); 

1) n is the binary integer to be converted. (Input) 

2) string is the character string in which to return the 

ASCII representation. (Output) 

Entry : c v — b i n_$ oc t 

This entry converts a binary integer of base 8 to a 
twelve-character ASCII string. 

Usage 

declare cv_bin_$oct entry (fixed bin, char(12)); 
call cv_bin__$oct (n, string); 
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j. / it 



is the binary integer to be converted. (Input) 



2) string is the character string in which to return the 

ASCII representation. (Output) 
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and Honeywell Information Systems Inc. (END) 



MULTICS PROGRAMMERS 1 MANUAL 



cv dec 



Subrout i ne Cal 1 
Standard Service System 

5/9/72 



Name ; cv_dec_ 

This procedure takes an ASCII representation of a decimal 
integer and returns the fixed binary(35) representation of that 
number . 

Usage 

declare cv_dec_ entry (char(*)) returns (fixed bin(35)); 
a = cv_dec_ (string); 

1) string is the string to be converted. It must be 

non-varying. (Input) 

2) a is the result of the conversion. (Output) 
Note 

The syntax of the string is a sequence of digits preceded by 
an optional plus or minus sign. Leading and trailing blanks are 
ignored. 

Entry : cv__dec_check_ 

This entry point differs from cv_dec_ only in that a code is 
returned indicating the possibility of a conversion error. It 
may be called as shown because the segment is multiply named. 

Usage 

declare cv_dec_check_ entry (char(*), fixed bin) 
returns (fixed bin(35)); 

a = cv__dec_check__ (string / code); 

1) string is the string to be converted. It must be 

nonvarying. (Input) 

2) code =0 if no error occurred; otherwise it is the 

index of the character that terminated the 
conversion. (Output) 

3) a is the result of the conversion. (Output) 
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Name : cv_di r__acl__ 

This subroutine/ given a pointer to a directory Access 
Control List (ACL), and the array index of a directory ACL entry, 
formats the entry for printing, returning the formatted string to 
the caller. Options allow suppression of the mode, process class 
identifier, and error message subfields. Refer to the MPM 
Reference Guide section, Access Control, for a discussion of 
access control and the subroutine writeup for hcs_$add_di r_acl_ 
entries for a description of a directory ACL structure. 

The formatted directory ACL entry that is returned has the 

form: 

sma User. Proj ect .* error_tabl e_ message 

Usage 

declare cv_dir_acl_ entry (ptr, fixed bin, char(*), 
fixed bin, bit(*)); 

call cv_dir_acl__ (acl_ptr, index, string, len, options); 

1) acl_ptr is a pointer to the ACL array, one of which is to be 

formatted. (Input) 

2) index is the array index of the ACL entry to be formatted. 

(Input) 

3) string is the resultant formatted string, containing the 

mode, process class identifier and error message as 
described above. (Output) 

k) len is the number of significant characters in string. 

(Output) 

5) options are control bits allowing suppression of various 
parts of the output: (Input) 

bit 1 on - include mode 

bit 2 on - include error_table_ message associated 

with the code in the directory ACL entry 
bit 3 on - suppress process class identifier. 
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Name : cv_dir_mode_ 



This procedure converts a character string representation of 
access mode directory attributes (e.g., "sma", "null", "n", "") 
to the proper bit string for insertion into an Access Control 
List (ACL) entry. Mode characters in the input string can be in 
any order, and embedded blanks are ignored. See the MPM 
Reference Guide section, Access Control, for a description of 
access mode attributes. 

Usage 

declare cv_d i r_mode_ entry (char(*), bit(*), fixed bin(35)); 
call cv_di r_mode__ (chars, bits, code); 

1) chars is the character string to be converted (e.g., "sma"). 

(Input) 

2) bits is the mode bit string corresponding to chars (e.g., 

"lll"b). (Output) 

3) code is a status code that has the value zero or 

error__table__$bad_acl_code. (Output ) 
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Name : cv_f 1 oa t_ 

This procedure converts a character string representation of 
a floating point number into a single precision floating point 
representation. if an illegal character is encountered its 
index in the string is returned and the number is set to O.OeO. 

Usage 

declare cv_float_ entry (char(*)/ fixed bin, float b!nC27)); 
call cv_float_ (string/ code, fnum); 

1) string is the character representation of the number. 

( I nput) 

2) code is the index in string of the first illegal 

character/ if one was found; otherwise it is zero. 
(Output) 

3) fnum is the number in floating point form. (Output) 

Entrv : cv_ f 1 oat_doubl e_ 

This entry is similar to cv__float_ except that the number 
returned is in double precision. 

Usage 

declare cv_f loa t__doubl e_ entry (char(*)/ fixed bin, 
float bin(63)); 

call cv_f loat_double_ (string, code, fnum); 

Same arguments as above. 

Note 

The input string should look like a PL/1 floating or fixed 
point constant. It does not need either an explicit exponent or 
a decimal point. 



(END) 
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Name : cv_mode_ 

This procedure converts a character string representation of 
access mode segment attributes (e.g., "rev*", "null", "n", or "") 
to the proper bit string for insertion into an Access Control 
List (ACL) entry. Mode characters in the input string can be in 
any order, and embedded blanks are ignored. 

Usage 

declare cv_mode_ entry (char(*), bit(*), fixed bin(35)); 
call cv_mode_ (chars, bits, code); 

1) chars is the character string to be converted (e.g., "rew"). 

(Input) 

2) bits is the mode bit string corresponding to chars (e.g., 

"lll"b). (Output) 

3) code is a status code that has the value zero or 

error__table_$bad__acl_code. (Output ) 
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Name : cv_oct_ 

This procedure takes an ASCII representation of an octal 
integer and returns the fixed binary(35) representation of that 
number. It may be called as shown because the segment is 
multiply named. 

Usage 

declare cv_oct_ entry (char(*) returns (fixed bin(35)); 
a = cv_pct__ (string); 

1) string is the string to be converted. It must be 

non-varying. (Input) 

2) a is the result of the conversion. (Output) 

Entrv : cv__oct_check_ 

This entry differs from cv__oct_ only in that a code is 
returned indicating the possiblity of a conversion error. It may 
be called as shown because the segment is multiply named. 

Usage 

declare cv_oct__check_ entry (char(*), fixed bin) 
returns (fixed bi n(35 ) ) ; 

a = cv__oct_check__ (string, code); 

1) string is the string to be converted. It must be 

non-varying. (Input) 

2) code =0 if no error occurred; otherwise it is the 

index of the character that terminated the 
conversion. (Output) 

3) a is the result of the conversion. (Output) 
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Name : cv_userid_ 

This procedure/ given an unnormalized process class 
identifier (e.g., "Multics"), returns a normalized identifier 
(e.g., "*.Mul ti cs. *") . See the MPM Reference Guide section, 
Access Control, for a discussion of process class identifiers. 

Usage 

declare cv_userid__ entry (char(*)) returns (char(32)); 
norma 1 id ■ cv__user i d__(arg); 

1) arg is the unnormalized process class identifier to be 

converted. (Input) 

2) normal_id is the resultant normalized identifier. If it has 

fewer than 32 characters, it is padded on the 
right with blanks. (Output) 



(c) Copyright, 1973, Massachusetts 
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Name : date_time_ 

The date_ time_ procedure converts a system clock reading to 
ASCII, It takes as an argument a clock reading (see dock_), 
fixed binary(71), and returns as an argument a 2k character 
nonvarying ASCII string. (If the caller declares the length to 
be less than 2k, the string Is truncated on the right; if greater 
than 2k, the string is padded on the right with blanks.) The 
string format is "mm/dd/yy hhmm.m 222 www" where www is a three 
letter abbreviation of the day of the week. Clock readings not 
corresponding to dates in the twentieth century (after 1/1/1901) 
are converted as "01/01/01 0000.0". The clock reading is 
assumed to be in microseconds relative to January 1/ 1901/ 
Greenwich Mean Time (GMT). The time returned is local standard 
t ime. 

declare date_time_ entry (fixed bin(71) / chart*)); 
call date__time_ (time, string); 

1) time is the clock reading. (Input) 

2) string is the ASCII string equivalent of time. (Output) 

Entrv : date_t ime_$f st ime 

This entry point performs the same function as the above 
entry point but accepts a 36 bit time (as used internally in the 
file system) as input. 



Usage 



declare date.. t ime_$f stime entry (fixed bin(35)/ char(*)); 
call date__time_$f stime (time, string); 
Same arguments as above. 



(END) 
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Name : decode_cl ock_val ue_ 

Given a calendar clock value, decode_clock_val ue__ will 
return the month, the day of the month, the year, the time of 
day, and the day of week it represents. In addition, the current 
time zone, used in the calculation, is returned. 



declare decode_cl ock__val ue_ entry (fixed bin(71), fixed bin, 
fixed bin, fixed bin, fixed bin(71), fixed bin, 
char ( 3) al i gned) ; 

call decode_cl ock_val ue_ (clock, month, dom, year, tod, dow, 



Usase 



zone) ; 



1) clock 



is the clock value to be decoded. (Input) 



2) month 



is the month (January = 1, December ■ 12). (Output) 



3) dom 



is the day of the month. (Output) 



k) year 



is the year. (Output) 



5) tod 



is the number of microseconds since midnight (the 
time of day). (Output) 



6) dow 



is the day of the week (Monday ■ 1, 
(Output) 



Sunday = 7). 



7) zone 



is the current time zone. (Output) 



c) Copyright, 1971, Massachusetts Institute of Technology 
All rights reserved. 
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Name : decode_descr i ptor_ 

This procedure extracts information from argument 
descriptors. It should be called by any procedure wishing to 
handle variable length or variable type argument lists. It can 
process both the old descriptor format used by Version 1 PL/1 and 
the new format used by Version 2 PL/1 and Fortran. The following 
type codes are used: 



TvDe 


Datum TvDe 


1 


rpa 1 f i xf»d hi narv chnr t 


2 


rpa 1 flxpd hi narv 1 on? 


3 


real float binarv short 




real float binarv lone 


5 


complex fixed binary short 


6 


complex fixed binary long 


7 


complex float binary short 


8 


complex float binary long 


9 


real fixed decimal 


10 


real float decimal 


11 


complex fixed decimal 


12 


complex float decimal 


13 


poi nter 


Ik 


offset 


15 


label 


16 


entry 


17 


structure 


18 


area 



decode__descr i ptor_ 
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19 bit string 

20 varying bit string 

21 character string 

22 varying character string 

23 file 

Usage 

declare decode_descr i ptor_ entry (ptr, fixed bin / 

fixed bin, bit(l) aligned, fixed bin, fixed bin, 
fixed bin); 

call decode_descr i ptor_ (pt, n, type, packed, ndims, size, 
seal e) ; 

1) pt points either directly at the descriptor to be 

decoded or at the argument list in which the 
descriptor appears. (Input) 

2) n controls which descriptor is decoded. If n is 0, 

pt points at the descriptor to be decoded; 
otherwise/ pt points at the argument list header 
and the nth descriptor will be decoded. (Input) 

3) type will be set to the data type specified by the 

descriptor. Type codes appearing in the old form 
of descriptor will be mapped into the new codes 
given earlier. The value 0 will be returned if an 
illegal type code is found in the old format 
descriptor. The value -1 will be returned if 
descriptors are not present in the argument list 
or if the nth descriptor does not exist. (Output) 

4) packed will be set to "l"b if the data item is packed. 

If an old format descriptor specifies a string, 
the value n l"b will be returned; otherwise, the 
value "0"b will be returned for old descriptors. 
(Output) 

5) ndims will be set to the number of dimensions specified 

by the descriptor. This value will be 0 or 1 for 
an old form of descriptor. (Output) 



6) size 



will be set to the arithmetic precision, string 
size, or number of structure elements of the 
datum. This value wi 1 1 be 0 i f an old form of 
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descriptor specifies a structure. (Output) 



7) scale will be set to the scale of an arithmetic value. 

This value will be 0 for an old form of 
descriptor. (Output) 



(END) 
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Subrout ine Cal 1 
8/20/73 



Name : decode_entryname_ 

This procedure, given a procedure entry point name of the 
form "alb", returns the reference name and entry point portions 
separately; i.e., "a" and "b". If "a" is supplied, "a" and "a" 
are returned. If "a$" is supplied, the entry point portion is 
blank on return. 



del decode_entryname_ entry (char(*), char(32), char(32)); 
call decode__entryname__ (name, rname, ename); 



Usage 



1) name 



is an entry point name; e.g., ,, a$b". (Input) 



2) rname 



is the reference name portion of name; e.g., "a". 
If it has fewer than 32 characters, it is padded on 
the right with blanks. (Output) 



3) ename 



is the entry point portion of name; e.g., "b". If 
it has fewer than 32 characters it is padded on the 
right with blanks. (Output) 



(c) Copyright, 1973, Massachusetts Institute of Technology 
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Name : delete_ 

The delete_ subroutine deletes segments and unlinks links. 
It asks questions if the segment to be deleted is protected/ and 
attempts to remove the protection. It has two entries: one is 
called with a path name, the other with a pointer to a segment. 
Both have a set of switches which tell delete^ what to do. If 
the specified entry is a segment/ it is terminated using the 
term_ subroutine. 

Entrv : delete__$path 

This entry is called with the path name of the segment or 
1 ink to be deleted. 

Usage 

declare delete__$path entry (char(*)/ char(*)/ bit(6)/ 
char(*)/ fixed b!n(35)>; 

call delete_$path (dname, ename, switches/ caller, code); 



1) dname 

2) ename 

3) switches 

f orce_sw 



is the directory in which the entry to be 
resides. (Input) 



deleted 



i s the entry wi thin 
deleted. (Input) 



the specified directory to be 



specifies the actions 
It consists of six 
below. (Input) 



to be taken 
switches in 



by this routine, 
the order 1 i s ted 



If force_sw is "l"b/ then delete^ will 
automatically attempt to delete the entry even if 
it is protected; if M 0"b/ the next switch is 
exami ned . 



question_sw If question_sw is "l"b/ delete_wi11 ask the user 
if the entry should be deleted. A negative 
response will cause delete_ to return the status 
code error_table_$action_not_per formed. If 
question_sw is "0"b/ delete_will just return if 
it is unable to delete the entry, with an 
appropriate storage system status code. 

dirctory_sw delete_ will only delete directories if this 
switch is "l"b. If the path name specified refers 
to a directory/ and this switch is "0"b, delete_ 



(c) Copyright/ 1972/ Massachusetts Institute of Technology 
All rights reserved. 



del ete. 



MULT ICS PROGRAMMERS 1 MANUAL 



Page 2 



will return with a status code of 
er ror_tabl e_$d i rseg. 

segment_sw delete_will delete segments only if this switch 
is "l"b. Multi-segment files are considered to be 
segments. If the path name specified refers to a 
segment/ and this switch is "0"b, delete^ will 
return a status code of error__table_$nondi rseg. 

link_sw delete_will delete (i.e. unlink) links only if 
this switch is n l n b. If the path name specified 
is a link/ and this switch is "0"b/ delete_ will 
return a status code of er ror__table_$not_a_branch. 

chase_sw If link_sw is "l"b/ and chase__sw is "l"b/ delete__ 
will "chase" the link/ and delete the segment that 
it poi nts to. 

k) caller is the name of the calling procedure/ to be used 

when questions are asked. (Input) 

5) code is a status code. (Output) 

Entry: de1ete_$ptr 

The ptr entry is similar to the path entry/ except that the 
caller has a pointer to the actual segment to be deleted. The 
di rectory_sW/ link_sw/ and chase__sw are not examined by this 
entry/ but must be present. 

Usage 

declare delete_$ptr entry (ptr # bit(6), char(*)/ fixed 
bin(35)); 

call delete_$ptr (segp/ switches/ caller/ code); 

1) segp is a pointer to the segment to be deleted. 

(Input) 

The other arguments are as above. 



@ Copyright/ 1972/ Massachusetts Institute of Technology 
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Name : d i scard__output_ 

This I/O System Interface Module ( I OS I M) provides a means by 
which output may be discarded. Any output written to a stream 
attached via the d i scard_putput_ module will be discarded / i.e., 
no operation is performed. All implemented I/O system calls will 
return information indicating successful completion of the 
operat ion . 

Usage 

call ios_$attach ( st ream_jiame, "d i scard_output_", "", 
status); 

Subsequent to the above attach call and until a corresponding 
detach call is made, all data written on stream_name will be 
d i scarded . 

I/O System Calls 

abort 
attach 
detach 
resetwr i te 
wr i te 

pev ice I dent i f icat ion 

Since no device or pseudo-device is involved, the device 
identification must be "". 

Status 

Only standard Multics error codes are returned as the first 
part of the status string. 

Detachment 

No special action is permitted when detaching. 



(c) Copyright, 1971, Massachusetts Institute of Technology 

All rights reserved. (END) 



MULT fCS PROGRAMMERS' MANUAL 



enci pher. 



Subrout i ne Cal 1 
8/16/73 



Name ; encipher., decipher. 

This subroutine enciphers and deciphers an array of double 
words. The caller supplies a 72-bit key that is used to generate 
an initial encoding, and subsequent keys are generated from the 
enciphered text. 

Entry : encipher. 

This entry point enciphers an array. 

Usage 

declare encipher., entry (fixed bin(71), (*)f ixed bin(71), 
(*)fixed bin(71), fixed bin); 

call encipher, (key, input, output, 1th); 

1) key is the input key. Any 72-bit key is appropriate and 

produces some enciphering of the array. (Input) 

-ray to be enciphered. (Input) 

iciphered array. (Output) 

sngth of the input and output arrays in 
fixed bin(71) elements. (Input) 

Entry: decipher. 

This entry point deciphers an array previously produced by 
encipher.. 

Usage 

declare decipher, entry (fixed bin(71), (*)fixed bin(71), 
(*)fixed bin(71), fixed bin); 

call decipher, (key, input, output, 1th); 

1) key is as above and should be the same as the key used 

to encipher the array if the original array is to be 
reproduced. (Input) 



2) 


i nput 


i s 


the 


3) 


output 


i s 


the 


k) 


1th 


i s 


the 



2) 


i nput 


i s 


the enciphered array 


to be deciphered. (Input) 


3) 


output 


i s 


the deciphered array. 


(Output) 


h) 


1th 


i s 


as above. (Input) 





© 
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Name : expand_path_ 

The expand_path_ procedure expands a relative pathname into 
an absolute pathname. 



See MPM Reference Guide Section 2 
Programming Environment". 



on "The Multics 



Usage 



declare expand_path__ entry (ptr, 
fixed bin); 



fixed bin, ptr, ptr, 



call expand_path_ (pnamep, pnamel, dirp, enamep, code); 

Below pname is used to denote the string pointed to by 
pnamep. 



1) pnamep 



2) pname 1 



3) dirp 



k) enamep 



is a pointer to the pathname to be 
expanded. It may point to an 
unaligned string. (Input) 

specifies the length of pname. If 0, 
pname is assumed to be the current 
working directory. (Input) 

is a pointer to a string in which 
either the directory pathname derived 
from pname or the entire pathname 
derived from pname will be stored. 
(See k, below.) It is assumed that 
dirp points to an aligned character 
string of length 168. (Input) 

is a pointer to a string in which the 
entry name derived from pname is to 
be stored. If enamep - null/ then 
the entire pathname derived from 
pname will be stored in dir. It is 
assumed that enamep points to an 
aligned character string of length 
32. (Input) 



5) code 



is an error code. (Output) 



expand_pat h_ 
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Error codes that can be returned are: 



1) error_tab1 e_$badpa th 

2) error_table_$di rlong 

3) error__table_$ent long 

k) error_table_$lesserr 
5) error__tabl e_$pathl ong 

Examples 



bad syntax in the pathname, 

the directory pathname Is longer than 
168 characters. 

the entry name is longer than 32 
characters • 

too many "< M, s In the pathname, 

the final pathname (directory name M 
entry name) is longer than 168 
characters. 



In all of the following examples, assume that the user's 
current working directory is >udd>dir>dl and that dir and ename 
stand for the string pointed to by dirp and enamep, respectively. 



InDut ( Dname) 




Output 






i f enamep is nul 1 


otherwi se 






dir 


ename 


fred 


>udd>dir>dl >fred 


>udd>dlr>dl 


fred 


< 


>udd>dir 


>udd 


dir 


<< 


>udd 


> 


udd 


<<george 


>udd>george 


>udd 


george 


<<george>harry 


>udd>george>har ry 


>udd>george 


harry 


>udd>jack>bi 11 


>udd>jack>bi 1 1 


>udd>jack 


bill 



(END) 
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Name: file_ 

This pseudodevi ce interface module enables a procedure to 
use segments and mu 1 t I -segment files as if they were I/O devices. 
For the sake of brevity/ this document shall use the term "file" 
to mean a segment or mu l t i -segment file. A file is made to 
appear as an I/O device by issuing an attach call as illustrated 
below. Once the attach call has been made, data may be read from 
or written to the file by the usual I/O read and write 
operations. Information on the I/O system can be found in the 
MPM Reference Guide section, Use of the Input and Output System. 

Usage 

call ios_$attach (stream_name/ "file.. 11 / filename, mode, 
status ) ; 

This call causes the file with absolute path name file_name to be 
attached as a pseudodevi ce via the stream s tream__name. All 
subsequent read or write calls to stream_name will cause data to 
be input from or output to the specified file. The same file 
should not be attached to more than one stream or by more than 
one process simultaneously. 

Permitted 1/0 System Qal Is 

attach 
detach 
getdel im 
getsi ze 
read 
seek 

setdel im 
setsi ze 
tell 
wr i te 

Device Identifiers 

The device identifier used in a call to attach must be the 
path name of the file to be used as a pseudodevi ce. 
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Mode? 

Only read and write modes are allowed by this I0SIM. The 
mode string in the attach call conforms to the conventions 
described in the MPM Reference Guide section/ Use of the Input 
Output System. The mode of a particular attachment may not be 
changed after the attach call. 

.status 

The first half of the status string is a standard Multics 
status code with zero indicating no error. In the second half of 
the status string, the stream name detached bit being on 
indicates the stream has been detached; the end of data bit being 
on indicates the last element has been read, or, more precisely, 
that the "read" reference pointer is beyond the "last" reference 
poi nter . 

Element Size 

Any element size up to 2,359,296 is permitted. This is the 
size of a 6UK segment. The default element size is 9. 

Read Del imi ters and Break Characters 

Any element can be a read delimiter subject to the following 
general restrictions. Read delimiters may not be established if 
the element size is greater than 72 or if an element could 
potentially span a segment boundary (i.e., the element size does 
not evenly divide the maximum segment size). For element sizes 
less than or equal to 9, any number of elements may be 
established as read delimiters. For element sizes greater than 
9, the maximum number of permitted read delimiters is the 
integral part of 720 divided by the element size. Note that 
changing the element size causes all currently established read 
delimiters to be discarded since the delimiters no longer make 
sense with a new element size. The default read delimiter is the 
"new line" character. Break characters are not implemented. 

Reference Pointers 

The reference pointers first, read, write, last, and bound 
are all implemented. The reference pointer "first" always has a 
value of zero and cannot be modified. The reference pointer 

"read" is initially set to the value of "first", while the 
reference pointer "write" is set to the value of "last". The 
pointer "last" is set to the last element of the file as 
indicated by the bit count. 



© Copyright, 1973, Massachusetts Institute of Technology 
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Svnchroni zat ion 

The file_ I/O System Interface Module (IOSIM) operates in 
read synchronous, write synchronous mode only. 

Detaching 

Detaching causes the bit length attribute of the file to be 
updated to the new value if the length of the file has been 
modified. No special actions are permitted during detachment. 



c) Copyright, 1973, Massachusetts Institute of Technology 
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Subroutine Call 
10/31/73 



Name : f indLcondi t ion__info_ 



This procedure is given a pointer to a stack frame being 
used when a condition occurred and returns information relevant 
to that condition. 

declare f ind__condi t ion_info_ entry (ptr/ ptr, 
fixed bin(35)); 

call f ind_condi tion_info_ (sp, c\p, code); 

1) sp is a pointer to a stack frame being used when a 

condition occurred. It is normally the result of a 
call to f i nd_condi t ion_f rame_; or if null/ the most 
recent condition frame is used. (Input) 

2) cip is a pointer to the following structure in which 

information is returned. (Input) 

declare 1 cond_info aligned/ 
2 mcptr ptr, 
2 version fixed bin, 
2 condi t ion_name char (52) varying/ 
2 infoptr ptr, 
2 wcptr ptr/ 
2 loc_ptr ptr, 
2 flags al igned/ 

3 crawlout bit(l) unaligned/ 

3 padl bit(35) unaligned/ 
2 pad2 bi t(36) al igned/ 
2 user_Joc__ptr ptr, 
2 padU) bit(36) aligned; 

1) mcptr if not null/ points to the machine 

conditions. Machine conditions are 
described in the MPM Reference 
Guide section/ The Multics 
Condition Mechanism. 

2) version is the version number of this 

structure (currently = 1). 

3) condi tion__name is the condition name. 

k) infoptr points to the info structure if 

there is one; otherwise it is null. 
The info structures for various 
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5) wcptr 



6) loc_ptr 



7) crawlout 



conditions are described in the MPM 
Reference Guide section. List of 
System Conditions and Default On 
Unit Actions. 

is a pointer to machine conditions 
describing a fault that caused 
control to leave the current ring. 
This occurs when the condition 
described by this structure was 
signalled from a lower ring and, 
before the condition occurred, the 
current ring was left because of a 
fault. Otherwise, it is null. 

is a pointer to the location where 
the condition occurred. If 
crawlout = "l"b, this points to the 
last location in the current ring 
before the condition occurred. 

if M l"b, indicates that the 
condition occurred in a lower ring 
but that it could not be adequately 
handled there. 



8) padl 

9) pad2 

10) user__loc_ptr 



is currently unused. 

is currently unused. 

is a pointer to the most recent 
non-support location before the 
condition occurred. If the 

condition occurred in a support 
procedure (e.g., a PL/ ! support 
routine), this makes it possible to 
locate the user call that preceded 
the condition. 



3) code 



11) pad 

is a standard 
sp does not 
nul 1 , when no 



is currently unused. 

system status code. It is nonzero when 
point to a condition frame or, if sp is 
condition frame can be found. (Output) 



(c) Copyright, 1973, Massachusetts Institute of Technology 
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f>|ame ; get_def aul t_wd i r_ 

This function returns the path name of the user's current 
default working directory. 

Usage 

declare get_def aul t_wdi r_ entry returns (char(168) aligned); 

defaul t_jwdi r = get_def aul t_jwdi r_; 

1) defaul t_wdir is the path name of the user's current 

default working directory. (Output) 



cj Copyright/ 1972, Massachusetts Institute of Technology 
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Name ; get__equai__name_ 

This procedure accepts an entry name and an equal name as 
its input, and constructs a target name by substituting 
components or characters from the entry name into the equal name, 
according to the Multics equal convention. Refer to the MPM 
Reference Guide section, Constructing and Interpreting Names, for 
a description of the equal convention and for the rules used to 
construct and interpret equal names. 

Usggg 

declare get_equa1__ name_ entry (char(*), char(*), char(32), 
fixed bin(35)); 

call get_equal_name_ (entryname, equal_name, target_name, 
code); 

1) entryname is the entry name from which the target is to be 

constructed. Trailing blanks in the entry name 
character string are ignored. (Input) 

2) equal__name is the equal name from which the target is to be 

constructed. Trailing blanks in the equal name 
character string are ignored. (Input) 

3) target__name is the target name that is constructed. (Output) 
k) code is one of the following status codes: (Output) 

0 the target name was constructed properly. 

error__tabl e_$bad__equal__name 

the equal name has a bad format. 

error_tabl e_$badequal 

there was no letter or component in the entry name 
that corresponds to a percent character (%) or an 
equal sign (=) in the equal name. 

e r ro r_tab 1 e_$ 1 ongeq 1 

the target name to be constructed would be longer 
than 32 characters. 

Note 

If the error_tabl e_$badequal status code is returned, then a 
target_name is returned in which null character strings are used 
to represent the missing letter or component of entryname. 
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if the e r ror_tab 1 e$ 1 ongeq 1 status code is returned/ then the 
first 32 characters of the target name to be constructed are 
returned as target__name. 

The entryname argument which is passed to get_equal_name__ 
can also be used as the target_name argument/ as long as the 
argument has a length of 32 characters. 



(c) Copyright/ 1973/ Massachusetts Institute of Technology 
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Name : get_group_i d_ 

The get_group_i d_ subroutine returns to the user the 
32-character access identifier of the process in which it is 
cal led. 

Usa.se 

declare get_group_id_ entry returns (char(32) aligned); 

char__string = get_group_i d_ (); 

1) char__string is a lef t- justi f ied character string padded with 
trailing blanks, which contains the access 
identifier. (Output) 

Entrv : get_group_i d_$ tag_star 

This entry point returns the access identifier of its caller 
with the instance component replaced by "*". 

Usage 

declare get_group_ id_$ tag_star entry returns 
(char(32) aligned); 

char_string - get_group_id_$tag_star (); 

1) char_string is as above. 



(c) Copyright, 1973/ Massachusetts Institute of Technology 
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Name ; get__pdir_ 

This subroutine returns the path name of the user's process 
directory. For a discussion of process directories/ see the MPM 
Reference Guide section/ The Storage System Directory Hierarchy. 

Usase 

declare get_pdir_ entry returns (char(168) aligned); 

char_string ■ get_pdir_ (); 

1) char_string is a left-justified character string/ padded 

with trailing blanks, which contains the path 
name of the -user's process directory. 
(Output) 



c) Copyright/ 1973/ Massachusetts Institute of Technology 
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Subroutine Call 
1/31/73 



Name ; get_p races s_i d_ 

The get__process_id_ subroutine returns to the user the 
36-bit identifier of the process in which it is called. 

Usage 

declare get_process_i d_ entry returns (bit(36)); 
bit_string = get_process_id_ (); 

1) bit_string is the 36-bit identifier of the process. (Output) 



(c) Copyright, 1973, Massachusetts 

and Honeywell 



Ipstitute of Technology 
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Name : get__wdir_ 

This function returns the pathname of the user's current 
working directory. 

Usage 

declare get__wdir_ entry returns (char(168) aligned); 

working^dir = get_wdir__; 

1) working^_dir is the pathname of the user f s current working 

directory. (Output) 



(END) 
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Subroutine Call 
2/12/73 



Name : hcs_$add__acl_entr i es 



This subroutine/ given a list of Access Control List (ACL) 
entries/ will add the given ACL entries/ or change their modes if 
a corresponding entry already exists, to the ACL of the specified 
segment. 



Usage 



declare hcs_$add_acl_entr i es entry (char(*)/ char(*)/ 
ptr 7 fixed bin/ fixed bin(35)); 



call hcs_$add_acl_entries (dirname/ ename, acl^ptr, 
acl__count/ code); 



1) dirname 

2) ename 

3) acl_ptr 
k) ac 1 __coun t 
5) code 



is the directory portion of the path name of the 
segment in question. (Input) 

is the entry name portion of the path name of the 
segment in question. (Input) 

points to a user-filled segment_acl structure. 
See Notes below. (Input) 

contains the number of ACL entries in the 
segment_acl structure. See Notes below. (Input) 

is a standard status code. (Output) 



Notes 



The following structure is used: 

del 1 segment.. acl (acl__count) aligned based (acl_ptr)/ 
2 access_name char(32)/ 
2 modes bi t(36)/ 
2 zero_pad bi t(36)/ 
2 status_code fixed bin(35); 

1) access__name is the access name (in the form 

person. project . tag) which identifies the 
processes to which this ACL entry applies. 

2) modes contain the modes for this access name. The 

first three bits correspond to the modes read, 
execute/ and write. The remaining bits must be 
zero. 
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3) zero_pad must contain zero. (ihis field is for use with 

extended access . ) 

k) status_code is a standard status code for this ACL entry 

only . 

If code is returned as error_tabl e$arger r then the offending 
ACL entries in segment_acl will have status_code set to an 
appropriate error and no processing will have been performed. 

If the segment is a gate (see the MPM Subsystem Writers 1 
Guide section, Intraprocess Access Control (Rings))/ then if the 
validation level is greater than Ring 1, then only access names 
that contain the same project as the user, and "SysDaemon" and 
"sys_control 11 projects will be allowed. If the ACL to be added 
is in error then no processing will be performed and the code 
error_tabl e_$ i nval i d_pro ject__f or_gate will be returned. 



(c\ Copyright, 1973, Massachusetts Institute of Technology 
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Name : hcs__$add_di r_acl_entr i es 



This subroutine/ given a list of Access Control List (ACL) 
entries, will add the given ACL entries, or change their 
directory modes if a corresponding entry already exists, to the 
ACL of the specified directory. 



Usage 



declare hcs_$add_di r_acl_entr i es entry (char(*), char(*), 
ptr, fixed bin, fixed bin(35)); 

call hcs_$add_di r_acl_entr i es (dirname, ename, acl_ptr, 
acl__count, code); 



1) dirname 

2) ename 

3) acl_ptr 
k) acl_ count 



is the path name of the directory superior to 
the one in question. (Input) 

is the entry name of the directory in 
question. (Input) 

points to a user-filled dir_acl structure. 
See Notes below. (Input) 

contains the number of entries in the dir_acl 
structure. See Notes below. (Input) 

is a standard status code. (Output) 



5) code 
Notes 

The following structure is used: 

declare 1 dir_acl (acl_count) aligned based (acl_ptr), 
2 access_name char(32), 
2 dir_modes bit(36), 
2 status_code fixed bin(35); 



1) access_name 



2 ) d i r modes 



3) status__code 



is the access name (in the form 
person . pro ject . tag) which identifies the 
process to which this ACL entry applies. 

contains the directory modes for this access 
name. The first three bits correspond to the 
modes status, modify, and append. The 
remaining bits must be zero. 

is a standard status code for this ACL entry 
onl y . 
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If code is returned as error_tab ie_$argerr then the 
offending ACL entries in the dir_acl structure will have 
status_code set to an appropriate error and no processing will 
have been performed. 
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hcs_$append_branch 



Subroutine Cal 1 
3/19/73 



Name : hcs_$append_branch 

This entry creates a segment in the specified directory/ 
initiates the segment's Access Control List (ACL) by copying the 
Initial ACL for segments found in the directory, and adds the 
user to the segment's ACL with the mode specified. ACLs and 
Initial ACLs are described in the MPM Reference Guide section. 
Access Control, 

usage 

declare hcs__$append_branch entry (char(*), char(*), 
fixed bin (5), fixed bin (35)); 

call hcs_$append_branch (dirname, entryname, mode, code); 

1) dirname is the path name of the directory in which segname 

is to be placed. (Input) 

2) entryname is the entry name of the segment to be created. 

(Input) 

3) mode is the user's access mode; see Notes below. (Input) 



k ) code is a standard storage system status code. (Output) 

Notes 

Append (a) access mode is required in the directory dirname 
to add an entry to that directory. 

A number of attributes of the segment are set to default 
val ues. 

1) Ring brackets are set to the user's current validation level. 
See the MPM Subsystem Writers' Guide section, Intraprocess 
Access Control (Rings). 

2) The user ID is set to the name and project of the user, with 
the instance tag set to *. 

3) The copy switch is set to 0. 
k) The bit count is set to 0. 

See the MPM write-up for hcs_$append_branchx to create a 
storage system entry with other values than the defaults listed 
above. 
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mode is encoded with one access mode specified by each bit. For 
segments the modes are: 

read 8-bit (i.e., 01000b) 

execute i*-bit (i.e., 00100b) 

write 2-bit (i.e., 00010b) 

For directories, the modes are: 

status 8-bit (i.e., 01000b) 

modify 2-bit (i.e., 00010b) 

append 1-bit (i.e., 00001b) 

The unused bits are reserved for unimplemented attributes and 
must be zero. For example, rw access in bit form is 01010b, and 
is 10 in fixed binary form. 
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hcs_$append_br anchx 



Subroutine Call 
3/20/73 



Name : hcs_ $append_branchx 

This entry creates either a subdirectory or a segment in the 
specified directory. (The entry point is really nothing more 
than an extended and more general form of hcs_$append_ branch. ) 
If a subdirectory is created then the subdirectory's access 
control list (ACL) is initiated by copying the Initial ACL for 
directories that is stored in the specified directory; otherwise 
the segment's ACL is initialized by copying the Initial ACL for 
segments. The input userid and mode (See Usage below) are then 
added to the ACL of the subdirectory or segment. 

Usage 

declare hcs__$append_br anchx entry (char(*) / char(*), fixed 
bin (5), (3) fixed bin (6), char(*) / fixed bin (1), 
fixed bin (1), fixed bin (2*0, fixed bin (35)); 

call hcs_$append_ branchx (dirname, entryname, mode, rings, 
userid, dirsw, copysw, bitcnt, code); 

1) dirname is the path name of the directory in which 

entryname is to be placed. (Input) 

2) entryname is the name of the segment or subdirectory to be 
created. (Input) 

is the user's access mode; see Notes below. 
(Input) 

are the new segment's or subdirectory's ring 
brackets; see the MPM Subsystem Writers' Guide 
section, Intraprocess Access Control (Rings). 
( Input) 

is the user's access control name of the form 
Person. Project .Tag. (Input) 

is the branch's directory switch (- 1 if a 
directory is being created; = 0 otherwise). 
(Input) 

is the segment copy switch (= 1 if a copy is 
wanted whenever the segment is initiated; = 0 i f 
the original is wanted). (Input) 

is the segment's length (in bits). (Input) 



3) mode 

k) rings 

5) userid 

6) dirsw 

7) copysw 

8) bitcnt 
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9) code 



is a standard storage 
(Output) 



system 



status 



code. 



Notes 



Append (a) access mode is required in the directory dirname 
to add an entry to that directory. 

The mode argument is a fixed binary number where the desired 
mode is encoded with one access mode specified by each bit. For 
segments the modes are: 

read 8-bit (i.e., 01000b) 

execute i»-bit (i.e., 00100b) 

write 2-bit (i .e., 00010b) 

For directories, the modes are: 

status 8-bit (i.e., 01000b) 

modify 2-bit (i.e., 00010b) 

append 1-bit (i.e., 00001b) 

Note that if modify access is given for a directory, then status 
must also be given; i.e., 01010b. The unused bits are reserved 
for unimpl emented attributes and must be zero. For example, rw 
access in bit form is 01010b, and is 10 in fixed binary form. 
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hcs_$append_l i nk 



Subrout i ne Cal 1 
2/16/73 



Name : ftcs_$append_] ! nk 

This subroutine is provided to create a link in the storage 
system directory hierarchy to some other directory entry in the 
hierarchy. For a discussion of links see the MPM Reference Guide 
section Segment/ Directory and Link Attributes. 

Usa ge 

declare hcs_$append_l i nk entry (char(*), char(*) char(*)/ 
fixed bin(35)); 

call hcs_$append__l i nk (di rename/ 1 i nk_name, path, code); 

1) di rename is the directory path name in which the link is to 

be created. ( I nput ) 

2) link__name is the entry name of the link to be created. 

( Input) 

3) path is the path name of the segment to which 1 i nk_name 

is to point. (Input) 

k) code is a standard storage system status code. (Output) 

Notes 

The user must have the append attribute with respect to the 
directory in which the link is being created. 

The entry pointed to by the link need not exist at the time 
the link is created. 

The subroutines h cs_$ a ppend_.br a nch and hcs_$append_branchx 
may be used to create a segment or directory entry in the storage 
system hierarchy. 
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hcs_$chname_f i 1 e 



Subrout i ne Call 
2/16/73 



Name ; hcs_$chname_f il e 



This subroutine changes an entry name on a storage system 
entry specified by path name. If an old (i.e., already existing) 
name is specified, it is deleted from the entry; if an new name 
is specified it is added. Thus, if only an old name is 
specified, the effect is to delete a name; if only a new name is 
specified, the effect is to add a name; and if both are 
specified, the effect is to rename the entry. 



usage 

declare hcs_$chname_f i 1 e entry (char(*), char(*), 
char(*), char(*), fixed bin(35)); 

call hcs_$chname_f i 1 e (dir_name, entry_name, oldname, 
newname, code); 

1) dir__name is the path name of the directory in which the 

entry to be manipulated is found. (Input) 

2) entry__name is the name of the entry to be manipulated. 

(Input) 

3) oldname is the name to be deleted from the entry. It may 

be a null character string ( ,m ) in which case no 
name is to be deleted. If oldname is null, then 
newname must not be null. (Input) 



k) newname is the name to be added to the entry. It must not 

already exist in the directory on this or another 

entry. It may be a null character string ("") in 
which case no name is added. If it is null, then 
oldname must not be the only name on the entry. 
( Input) 

5) code is a standard storage system status code. It may 

have the values: 



er ro r_t ab 1 e_$ no n amer r 
error_tabl e_$namedup 
error_table_$segnamedup (Output) 

Notes 

The subroutine hcs__$chname_seg performs the same function, 
given a pointer to the segment instead of its path name. 
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The user must have the modify attribute with respect to the 
directory in question. 

Exampl es 

Assume that the entry >my_di r >a1 pha exists and that it also 
has the entry name beta. Then the following calls to 
hcs_$chname_f i 1 e would have the effects described. 

call hcs_$chname_f i le (">my_dir", "alpha", "beta", "gamma", 
code) ; 

This call would change the entry name beta to gamma. 

call hcs_$chname__f i le (">my_dir", "gamma", "gamma", "", 
code) ; 

This call would remove the entry name gamma. Note that any entry 
name may be used in the second argument position. 

call hcs_$chname_f i le (">my_dir", "alpha", "", "delta", 
code); 

This call would add the entry name delta. The entry now has the 
names alpha and delta. 
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h cs_$ c h n ame__s e g 



Subroutine Call 
2/13/73 



Name : hcs__$chname_seg 

This subroutine changes an entry name on a storage system 
segment/ given a pointer to the segment. If an old (i.e., 
already existing) name is specified, it is deleted from the 
entry; if a new name is specified, it is added. Thus, if only an 
old name is specified, the effect is to delete a name; if only a 
new name is specified, the effect is to add a name; and if both 
are specified, the effect is to rename the entry. 



Usage 



declare hcs_$chname_seg entry (ptr, char(*), char(*), 
fixed bin(35)); 

call hcs_$chname_seg (seg__ptr, oldname, newname, code); 



1) seg_ptr 

2) oldname 

3) newname 



k) code 



is a pointer to the segment 
changed. (Input) 



whose name will be 



is the name to be deleted from the entry. It may 
be a null character string ("") in which case no 
name is to be deleted. If oldname is null, then 
newname must not be null. (Input) 

is the name to be added to the entry. It must not 
already exist in the directory on this or another 
entry. If may be a null character string ("") in 
which case no name is added. If it is null, then 
oldname must not be the only name on the entry. 
( Input) 



is a standard storage system status code, 
have the values: 

er ror_tab1e_$namedup 

error_tab_$nonemer r 

error__tabl e_$segnamedup (Output) 



1 1 may 



Notes 



The subroutine hcs_$chname_f i 1 e performs the same function, 
given the directory and entry names of the segment instead of the 

poi nter . 

The user must have the modify attribute with respect to the 
directory in question. 
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Examples 

Assume that the user has a pointer, seg__ptr, to a segment 
which has two entry names, alpha and beta. Then the following 
calls to hcs_ $chname_seg would have the effects described. 

call hcs_$chname_seg (seg_ptr, "beta"/ "gamma"/ code); 
This call would change the entry name beta to gamma. 

call hcs__$chname_seg (seg_ptr, "gamma", "", code); 
This call would remove the entry name gamma. 

call hcs_$chname_seg (seg_ptr / "", "delta", code); 

This call would add the entry name delta. The entry now has the 
names alpha and delta. 
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hcs_$del_di r_t ree 



Subroutine Call 
2/21/73 



Name ; hcs_$del_di r_tree 

This subroutine deletes a subtree of the storage system 
hierarchy, given the path name of a directory. All segments, 
links and directories inferior to that directory are deleted 
including the contents of any inferior directories. The 
specified directory is not itself deleted; to delete it, see the 
MPM write-ups for hcs_$del entry_f i 1 e and hcs_$del entry_seg. 

Usage 

declare hcs_$del_di r_tree entry (char(*), char(*), 
fixed bin(35)); 

call hcs_$del_di r_tree (parent_name, di r_name, code); 

1) parent_name is the path name of the parent directory of the 

directory whose subtree is to be deleted. (Input) 

2) di rename is the entry name of the directory whose subtree 

is to be deleted. (Input) 

3) code is a standard storage system status code. 
Note 

The user must have the status and modify attributes with 
respect to the specified directory and the safety switch must be 
off in that directory. If the user does not have status and 
modify attributes on inferior di rector ies, hcs_$de1_di r_tree will 
provide them. 

If an entry in an inferior directory gives the user access 
only in a ring lower than his validation level/ that entry will 
not be deleted and no further processing will be done on the 
subtree. For those users who need to know about rings, they are 
discussed in the MPM Subsystem Writers 1 Guide section, 
Intraprocess Access Control (Rings). 
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hcs__$del entry_f i 1 e 



Subroutine Call 
3/15/73 



Name : hcs_ $del ent ry_f i 1 e 

This subroutine, given a directory name and an entry name, 
deletes the given entry from its parent directory. If the entry 
is a segment the contents of the segment are deleted first. If 
the entry specifies a directory which contains entries the status 
code error_table_$f ul ldi r is returned and hcs_$del_di r_tree must 
be called to remove the contents of the directory. 

Usage 

declare hcs_$delentry_f i 1 e (char(*), char(*), 
fixed bin(35)); 

call hcs_$delentry_f i 1 e (dirname, ename, code); 

1) dirname is the parent directory name. (Input) 

2) ename is the entry name to be deleted. (Input) 

3) code is a standard storage system status code. (Output) 
Notes 

The subroutine hcs_$del entry_seg performs the same function, 
given pointer to the segment instead of the pathname. 

The user must have modify permission with respect to 
dirname. If ename specifies a segment or directory rather than a 
link, the safety switch of the segment or directory must be off. 
For a temporary period the user must have write permission with 
respect to the segment or modify permission with respect to the 
directory being deleted. 
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hcs_$delent ry_seg 



Subroutine Call 
3/1U/73 



Name : hcs_$delentry_seg 

This subroutine/ given the pointer to a segment, deletes the 
corresponding entry from its parent directory. If the entry is a 
segment the contents of the segment are deleted first. If the 
entry specifies a directory which contains entries the status 
code error_tabl e_$f ul 1 di r is returned and hcs_$del_di r__tree must 
be called to remove the contents of the directory. 

Usage 

declare hcs_$delentry_seg (ptr, fixed bin(35)); 
call hcs_$delentry__seg (sp, code); 

1) sp is the pointer to the segment to be deleted. (Input) 

2) code is a standard storage system status code. (Output) 
Notes 

The subroutine hcs_$delentry__f i 1 e performs the same 
function, given the directory and entry names of the segment 
instead of the pointer. 

The user must have modify permission with respect to the 
segment's parent directory. The safety switch of the segment 
must be off. For a temporary period the user must have write 
permission with respect to the segment. 
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hcs_$del e te_ac l_entr i es 



Subroutine Call 
2/12/73 



Name ; hcs__$del ete_acl_entr i es 

This subroutine is called to delete specified entries from 
an Access Control List (ACL) for a segment. 

Usage 

declare hcs_$del ete_acl_entr i es entry (char(*)/ charC*), 
ptr, fixed bin, fixed bfn(35)); 

call hcs_$del ete_acl_entr i es (dirname/ ename/ acl_ptr/ 
acl__count/ code); 

1) dirname is the directory portion of the path name of the 

segment in question. (Input) 

2) ename is the entry name portion of the path name of the 

segment in question. (Input) 

3) acl_ptr points to a user-filled delete_acl structure. See 

Notes below. (Input) 

k) acl__count contains the number of ACL entries in the 
delete__acl structure. See Notes below. (Input) 

5) code is a standard status code. (Output) 

Notes 

The following structure is used: 

declare 1 delete_acl (acl count) aligned based (acl_ptr), 
2 access_name char (32), 
2 status_code fixed bin(35); 

1) access_name is the access name (in the form of 

person. pro ject . tag) which identifies the ACL 
entry to be deleted. 

2) status_code is a standard status code for this ACL entry 

onl y . 

If code is returned as error_tab 1 e__$arger r then the 

offending ACL entries in the de1ete_acl structure will have 
status_code set to an appropriate error and no processing will 
have been performed. 
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If an access name cannot be matched to one existing on the 
segment's ACL then the status code of that ACL entry is set to 
error_tabl e__$user_not_found, processing continues to the end of 
the delete_acl structure and code is returned as zero. 
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hcs_$del ete_di r_ad_ent r i es 



Subrout i ne Cal 1 
2/13/73 



Name ; hcs_$delete_di r__acl_entr les 



This subroutine is used to delete specified entries from an 
Access Control List (ACL) for a directory. The de 1 ete__ac 1 
structure used by this subroutine is described in the MPM 
write-up for hcs_ $del ete_acl_entr i es. 



declare hcs_$delete_di r_acl_entr i es entry (char(*), 
char(*), ptr, fixed bin, fixed bin(35)); 

call hcs_$del ete_di r_ad_entr i es (dirname/ ename, acl_ptr, 
acl_count, code); 



1) di rname 

2) ename 

3) acl_ptr 

k) ad__ count 

5) code 
Note 



is the path name of the directory superior to the 
one in question. (Input) 

is the entry name of the directory in question. 
( I nput ) 



poi nts to a 
(I nput) 



is the number of ACL entries 
structure, (input) 



user-filled delete_acl structure. 

in the del ete_acl 
is a standard status code. (Output) 



The status code 
hcs_$del ete_acl_entr ies. 



is interpreted as described in 
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h cs_$ f s_g e t_mo d e 



Subroutine Call 
3/8/73 



Name : hcs_$f s__get_mode 



This subroutine returns the access mode of the user, at the 
current validation level/ with respect to a specified segment. 
For a discussion of access modes, see the MPM Reference Guide 
section, Access Control. 

Usage 

declare hcs_$f s__get_mode entry (ptr, fixed bin(5), 
fixed bin(35)); 

call hcs_$f s_get_mode (segptr, mode, code); 

1) segptr is an pointer to the segment in question. (Input) 

2) mode is the mode (see Notes below). (Output) 

3) code is a standard storage system status code. 

(Output) 

Notes 

The mode and ring brackets for the segment in the user's 
address space are used in combination with the user's current 
validation level to determine the mode the user would have if he 
accessed this segment. For a discussion of ring brackets and 
validation level, see the MPM Subsystem Writers' Guide section, 
Intraprocess Access Control (Rings). 

The mode argument is a fixed binary number where the desired 
mode is encoded with one access mode specified by each bit. For 
segments the modes are: 

read 8-bit (i.e., 01000b) 

execute U-bit (i.e., 00100b) 

write 2-bit (i.e., 00010b) 

For directories, the modes are: 

status 8-bit (i.e., 01000b) 

modify 2-bit (i.e., 00010b) 

append 1-bit (i.e., 00001b) 

Note that if modify access is given for a directory, then status 
must also be given; i.e., 01010b). The high-order bit is 
reserved for an unimpl emented attribute and must be zero. For 
example, rw access in bit form is 01010b, and is 10 in fixed 
binary form. 
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h c s_$ f s_ge t_pa t h__n ame 



Subroutine Call 
2/28/73 



Name ; hcs_$f s_get_path_ name 

This entry, given a pointer to a segment/ returns a path 

name for the segment, with the directory and entry name portions 

of the path name separated. The entry name returned is the 

primary name on the entry; see the MPM Reference Guide section. 



Segment, Directory 
primary names. 



and Link Attributes for a discussion of 



declare hcs_$f s__get_ path_name entry (ptr, char(*), 
fixed bin, char(*), fixed bin(35)); 

call hcs_$f s_ get__path_name (segptr, dirname, ldn, ename, 
code); 



1) segptr 

2) dirname 



is a pointer to the segment in question. (Input) 

is the path name of the directory superior to the 
segment pointed to by segptr. If the length of 
the path name to be returned is greater than the 
length of dirname, the path name will be 
truncated. To avoid this problem, the length of 
dirname should be 168 characters. (Output) 



3) ldn 
k) ename 



is the number of nonblank characters 
(Output) 



in dirname. 



is the primary entry name of the segment pointed 
to by segptr. If the length of the entry name to 
be returned is greater than the length of ename, 
the entry name will be truncated. To avoid this 
problem, the length of ename should be 32 
characters. (Output) 



5) code 



is a standard storage 
(Output) 



system status code. 
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h c s_$ f s_g et_re f_n ame 



Subrout ine Cal 1 
Standard Service System 

8/2U/71 



Name : hcs__$f s_get_ref_name 

This entry point returns a specified (i.e., first, second, 
etc.) reference name for a specified segment. 



Usage 



1) 

2) 

3) 
h) 



declare hcs_$f s_get_ref_name entry (ptr, fixed bin, 
char(*), fixed bin); 

call hcs_$f s_get_ref_name (segptr, count, rname, code); 

segptr 



count 

rname 
code 



is a pointer to the segment in question. 
(Input) 

specifies which reference name is to be 
returned. See Notes . (Input) 

is the desired reference name. (Output) 

is a standard file system status code. 
(Output) 



Notes 



If "count 11 = 1, the name by which the segment has most 
recently been made known will be returned. If "count" = 2, the 
second most recently added name is returned and so on. If 
"count" is larger than the total number of names, the name by 
which the segment was originally made known is returned and 
"code" is set to error__table__$ref_count__too__b ig. 

See the MPM Reference Guide Section on naming conventions. 
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h c s_$ f s__ge t_s e g_p t r 



Subroutine Call 
2/16/73 



Entry : hcs_$f s_get_seg_pt r 



Given a reference name of a segment/ hcs_$f s__get_seg_ptr 
returns a pointer to the base of the segment. For a discussion 
of reference names, see the MPM Reference Guide section. 
Constructing and Interpreting Names. 

Usage 



declare hcs_$f s_get_seg_pt r entry (char(*), ptr, 
fixed bin(35)); 

call hcs_$f s_get_seg_ptr (rname, segptr, code); 



1) rname is the reference name of a segment for which a 

pointer is to be returned. (Input) 

2) segptr is a pointer to the base of the segment. (Output) 

3) code is a standard status code. (Output) 



Note 



If the reference name is accessible from the user f s current 
validation level, segptr is returned pointing to the segment; 
otherwise, it is null. The user who needs to know about rings 
and validation levels can find a discussion of them in the 
Subsystem Writers 1 Guide section, Intraprocess Access Control 
(Rings) . 
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hcs_$f s_move_f i le 



Subroutine Call 
2/27/73 



Name ; hcs_$f s_move__f i 1 e 

This subroutine moves the data associated with one segment 
in the storage system hierarchy to another segment given the path 
names of the segments in question. The old segment remains, 
with a zero length. 

Usage 

declare hcs_$f s_move_f i 1 e entry (char(*), char(*), 

fixed bin(2), char(*), char(*), fixed bin(35)); 

call hcs_$f s__move_f i 1 e (from_dir, from__entry, at_sw, to_dir, 
to_entry, code); 

1) from_dir is the path name of the directory in which 

from_entry resides. (Input) 

2) from_entry is the entry name of the segment from which data 

is to be moved. (Input) 

3) at_sw see Notes below. (Input) 

h) to__dir is the path name of the directory in which 

to_entry resides. (Input) 

5) to_entry is the entry name of the segment to which data is 

to be moved. (Input) 

6) code is a standard storage system status code. It may 

have the value er ror_tabl e_$no__move if either 
entry is not a segment, or one of the values 
described in Notes below. 

Notes 

The input argument at_sw is a 2-indicator switch which 
directs the procedure to use certain options. The two options 
specified are .append option and .truncate option. If the append 
option (high-order bit) is on, then append to_entry to to_dir if 
it does not already exist. If the append option is off and the 
destination entry can not .be found the status code 
error_table_$noentry is returned. 
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If the truncate option Clow-order bit) is on, to_entry is 
truncated if it is not zero length. Otherwise (i.e./ if the 
option is off and the length of to_entry is not zero) the status 
code error__table__$clnzero is returned. In both of the cases 
where the move is not completed/ the procedure will attempt to 
return the data to the original segment. 

The subroutine hcs_$f s__move_seg performs the same function 
given pointers to the segments in question instead of path names. 



@ Copyright/ 1973/ Massachusetts Institute of Technology 
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hcs_$f s_move_ seg 



Subroutine Call 
2/28/73 



Name 



hcs_$f 5_mo v e_s e g 



This subroutine moves the data associated with one segment 
in the hierarchy to another segment, given pointers to the 
segments in question. The old segment remains, with a zero 
1 ength. 



Usage 



declare hcs_$f s_move_seg entry (ptr, ptr, fixed bind), 
fixed bin(35)); 

call hcs_$f s__move_seg (from_ptr, to_ptr, trunsw, code); 



1) from__ptr 



is the pointer to the segment from which data 
to be moved. (Input) 



i s 



2) to_ptr 

3) trunsw 



is the pointer to the target segment. (Input) 

if equal to 1, then truncate the segment specified 
by to_ptr (if it is not already zero-length) 
before performing the move; 

if equal to 0, then reflect the status code 
error_tabl e_$cl nzero if that segment is not 
already zero-length. (Input) 



k) code 



is a standard storage system status code. Besides 
the value given under trunsw above, it may also 
have the value error_table_$no_move. (Output) 



Note 

The subroutine hcs__$f s__move_f i le performs the same function 
given the path names of the segments in question instead of the 
poi nters . 
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hcs_$ i n i 1 i ate 



Subroutine Call 
3/12/73 



Name ; hcs_$ i n i t i a te 



This subroutine is used to search for a segment/ make a copy 
of it if the copy switch so indicates, and make the segment or 
its copy known to the process. The reference name specified is 
entered in the address space of the process and a pointer to the 
segment is returned. If segsw is pji, then the segment pointer 
is input and the segment is made known with that segment number. 



Usage 



declare hcs_$ i n i t i ate entry (char(*)/ char(*)/ char(*), 
fixed bind), fixed bin(2)/ ptr, fixed bin(35)); 

call hcs__$ i n i t i ate (pname/ ename/ rname/ segsw / copysW/ 
segptr, code); 



1) pname 

2) ename 

3) rname 

h) segsw 

5) copysw 



6) segptr 

7) code 



is the path name of the directory containing the 
segment. (Input) 

is the entry name of the segment. (Input) 

is the reference name. If it is zero in length/ 
the segment is initiated by a null name. (Input) 

is the reserved segment switch: 

= 0 if no segment number has been reserved; 

■ 1 if a segment number was reserved. (Input) 

is the copy switch: 

s 0 if it is desired to go by the setting in the 
directory entry; 

■ 1 if no copy is wanted; 

= 2 if a copy is always wanted. (Input) 

is a pointer to the segment. (It is Input if 
segsw - i. Otherwise/ it is Output.) 



is a standard storage 
(Output) 



system status code. 
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Notes 

The user must have non-null access on the segment ename in 
order to initiate it. 

If ename cannot be initiated, a null pointer is returned for 
segptr and the returned value of code indicates the reason for 
failure. If ename is already known to the user's process, code 
is returned as error__table_$segknown and the the argument segptr 
will contain a valid pointer to ename. If ename is not already 
known, and no problems are encountered, segptr will contain a 
valid pointer and code will be zero. 
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hcs_$ i n 1 1 i a te_coun t 



Subrout ine Cal 1 
3/12/73 



ame : hcs__$ i n i t i ate_count 



This subroutine, given a path name and a reference name, 
causes the segment defined by the path name (or a copy of it, 
depending upon the copysw option) to be made known by the given 
reference name, A segment number is assigned and returned as a 
pointer and the bit count of the segment is returned. 



usage 



declare hcs_$ i n i t i ate_count entry char(*), char(*), char(*>, 
fixed bin(2*0, fixed bin(2), ptr, fixed bin(35)); 

call hcs_$ in i t iate_count (pname, ename, rname, bitcount, 
copysw, segptr, code); 



1) pname 

2) ename 

3) rname 

k) bitcount 

5) copysw 



6) segptr 

7) code 



is the directory portion of the path name of the 
segment in question. (Input) 

is the entry name portion of the path name of the 
segment in question. (Input) 

is the desired reference name. If it is zero in 
length, the segment is initiated by a null name. 
( Input) 

is the bit count of the segment. (Output) 

is the copy switch: 

= 0 if it is desired to go by the setting in the 

hierarchy entry; 
= 1 if no copy is wanted; 
= 2 if a copy is always wanted. (Input) 

is a pointer to the segment in question. (Output) 

is a standard storage system status code. 
(Output) 
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Notes 

The user must have non-null access on the segment ename in 
order to Initiate it. 

If ename cannot be initiated, a null pointer is returned for 
segptr and the returned value of code indicates the reason for 
failure. If ename is already known to the user's process, code 
is returned as error_table_$segknown and the argument segptr will 
contain a valid pointer to ename. If ename is not already known, 
and no problems are encountered, segptr will contain a valid 
pointer and code will be zero. 

See also the MPM Reference Guide section, Constructing and 
Interpreting Names. 



(c\ Copyright, 1973, Massachusetts Institute of Technology 

and Honeywell Information Systems Inc. (END) 



MULT ICS PROGRAMMERS 1 MANUAL 



hcs_$l i s t_acl 



Subrout i ne Cal 1 
2/15/73 



Name : hcs_$list_ acl 



This subroutine is used to either list the entire Access 
Control List (ACL) of a segment or to return the access modes 
from specified entries. The segment_acl structure used by this 
subroutine is described in the MPM write-up for 
hcs_$add_acl_entr i es . 



Usage 



declare hcs_$ 1 i st_ acl entry( char ( *) , char(*), ptr, ptr, 
ptr / fixed bin, fixed bin(35)); 

call hcs_$ 1 i st_acl (dirname, ename, area_ptr, area_ret_ptr, 
acl_ptr, acl_count, code) 



1) dirname 



2) ename 



3) area_ptr 



h) area_ret_ptr 



5) acl_ptr 



6) acl_count 



7) code 



is the directory portion 
the segment in question. 



of the path 
( Input) 



name of 



is the entry 
the segment 



name portion of the path name of 
n question. ( 1 nput) 



points to an area into which the list of 
entries is to be allocated. (Input) 



ACL 



points to the 
ACL entries. 



start of 
(Output) 



the allocated list of 



if area_ptr is 

to point to 

i nto whi ch mode 

for the ac 
structure. 



null then acl_ptr is assumed 
an ACL structure, segment_acl, 
information i s to be placed 
mes specified in that same 



cess na 
(Input) 



is the number of entries in the ACL structure 
identified by acl_ptr (Input); or is set to 
the number of entries in the segment_acl 
structure allocated in the area pointed to by 
area_ptr, if area_ptr is not null. (Output) 

is a standard status code. (Output) 



Note 



If acl_ ptr is used to obtain modes for specified access 
names (rather than obtaining modes for all access names on a 
segment), then each ACL entry will either have a zero code and 
will contain the segment's mode or will have code set to 
error_tab 1 e_$ user_not_f ound and will contain a zero mode. 
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hcs_$ 1 i st_di r__acl 



Subrout i ne Cal 1 
2/13/73 



Name : hcs_$ 1 i s t_di r_acl 



This subroutine is used to either list the entire Access 
Control List (ACL) of a directory or to return the access modes 
for specified entries. The dir_acl structure described in 
hcs_$add_d i r_acl_entr i es is used by this subroutine. 



declare hcs_$ 1 i st_di r_acl entry (char(*), char(*) / ptr, 
ptr, ptr, fixed bin, fixed bin(35)); 

call hcs_$ 1 i st_di r_acl (dirname, ename, area_ptr, 
area_ret__ptr, acl_ptr, acl_count, code); 



1) di rname 

2) ename 

3) area_ptr 

k) area_ret_j>tr 

5) ad_ptr 

6) acl_count 



is the path name of the directory superior 
the one in question. (Input) 



to 



is the entry name of the directory in question. 
( Input) 



points to an area into which the list 
entries is to be allocated. (Input) 



of ACL 



7) code 
Note 



points to the start of the list of the ACL 
entries. (Output) 

if area__ptr is null then acl_ptr is assumed to 
point to an ACL structure, di r_acl , into which 
mode information is to be placed for the access 
names specified in that same structure. (Input) 

is either the number of entries in the ACL 
structure identified by acl_ptr (Input); or if 
area_ptr is not null, then it is set to the 
number of entries in the dir_acl structure that 
has been allocated. (Output) 

is a standard status code. (Output) 



If acl_ptr is used to obtain modes for specified access 
names (rather than obtaining modes for all access names on a 
segment), then each ACL entry will either have a zero code and 
will contain the directory's mode or will have code set to 
er ror_tabl e__$user_not_f ound and will contain a zero mode. 



(c) Copyright, 1973, Massachusetts Institute of Technology 

and Honeywell Information Systems Inc. (END) 



MULT ICS PROGRAMMERS 1 MANUAL 



hcs__$make_pt r 



Subroutine Call 
Standard Service System 

1/17/72 



Name : hcs_$make_pt r 

This entry/ when given a segment name and an entry point 
name^ returns a pointer to a segment entry point. It uses the 
search rules to find the required segment. 

Usage 

declare hcs_$make_ptr entry (ptr, char(*), char(*), ptr, 
fixed bin); 

call hcs_$make_pt r (cal 1 er__ptr, seg_name, entry__po i nt_name, 
entry__poi nt_ptr, error_code) ; 

1) caller_ptr is a pointer to the "calling procedure" (see 

Notes below). (Input) 

2) seg_ name is the name of segment to be located. 

(Input) 

3) entry_point__name is the name of the entry point to be located. 

(Input) 

k) ent ry__poi nt_pt r is the pointer to the segment entry point 

specified by seg_name and ent ry_po i nt_name . 
(Output) 

5) error__code is the returned error code. (Output) 

Notes 

The directory in which the procedure pointed to by 
caller__ptr is located is used as the calling directory for the 
standard search rules. If it is null, then rule 1 of the 
standard search rules is skipped. See the MPM Reference Guide 
section on The System Libraries and Search Rules. The standard 
usage is to have caller_ptr null. 

The seg_name and entry_jx> i nt_name arguments are nonvarying 
character strings of length <. 32. They need not be aligned and 
may be blank padded. 

If a null string is given for the entry_poi nt_name argument, 
then a pointer to the base of the segment is returned. In either 
case, the segment seg__name is made known to the process with the 
reference name seg_name. If an error was encountered upon 
return, the entry_point_ptr argument is null and a nonzero error 
code is given. 
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To invoke the procedure entry point pointed to by 
entry_point__ptr / use cu__$gen_cal 1 or cu_$pt r__cal 1 . (See cu__ in 
the MPM.) 

Example 

The following PL/ I statements will generate a call to the 
procedure fred$foo passing as arguments the integer 17, the 
pointer p, and the character string "treat 11 . 

call hcs_$make_ptr (null, "fred", "foo", ep, code); 

call cu__$ptr_cal 1 (ep, 17, p, "treat"); 



(c) Copyright, 1972, Massachusetts Institute of Technology 
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hcs_$make__seg 



Subroutine Call 
Standard Service System 

2/16/72 



Name ; hcs_$make_seg 

This procedure creates a segment in a specified directory 
with a specified entry name. Once the segment is created, it is 
made known to the process by a call to hcs_$ ini t iate and a 
pointer to the segment is returned to the caller. If the segment 
already exists, an error code is returned. However, a pointer to 
the segment is still returned. 

Usage 

declare hcs_$make_seg entry (char(*), char(*), char(*), 
fixed bin(5), ptr, fixed bin); 

call hcs__$make_seg (dirname, entry, rname, mode 
segptr, code); 

1) dirname is the directory in which to create the segment. 

( Input) 

2) entry is the entry name of the segment to be created. 

(Input) 

3) rname is the desired reference name, or (Input) 

h) mode specifies the mode for this user. See Notes in 

hcs_$append_branch for more information on modes. 
( Input) 

5) segptr is a pointer to the created segment. (Output) 

6) code is a standard file system status code. (Output) 
Notes 

If dirname is null, the process directory is used. If the 
entry argument is null, a unique name is provided. The rname 
argument is passed directly to hcs_$ in i t iate and should normally 
be null. 

See also the MPM Reference Guide section on Constructing and 
Interpreting Names. 
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hcs__$repl ace_acl 



Subrout ine Cal 1 
2/13/73 



Name : hcs_$repl ace_acl 

This subroutine replaces an entire Access Control List (ACL) 
for a segment with a user-provided ACL/ and can optionally add an 
entry for *.SysDaemon.* with mode rw to the new ACL. The 
segment_acl structure described in hcs_$add_acl_entr ies is used 
by this subroutine. 



Usage, 



declare hcs_$repl ace_acl entry (char(*)/ char(*), ptr, 
fixed bin, bit(l), fixed bin(35)); 

call hcs__$repl ace__acl (dirname/ ename, ad_ptr/ acl__count, 
no_sysdaemon_sw, code); 



1) dirname 

2) ename 

3) acl_ptr 

k) acl_count 

5) no_sysdaemon_sw 



is the directory portion of the path name 
the segment in question, (input) 



of 



is the entry name portion of the path name of 
the segment in question. (Input) 

points to the user supplied segment_acl 
structure that is to replace the current ACL. 
(Input) 



is the number of entries in 
structure. (Input) 



the segment_acl 



if 
be 



"Q"b, then a *. SysDaemon. * rw entry will 
put on the segment's ACL after the 



existing ACL has been deleted and before the 
user supplied segment_acl entries are added; 
if "l M b, then only the user-supplied 
segment_acl will replace the existing ACL. 
(Input) 

6) code is a standard status code. (Output) 

Notes 

If acl_count is zero then the existing ACL will be deleted 
and only the action indicated by no_sysdaemon_sw will be 
performed (if any). In the case when acl__count is greater than 
zero, processing of the segment_acl entries is performed top to 
bottom/ allowing later entries to overwrite previous ones if the 
access_name parts are identical. 
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If the segment is a gate (see the MPM Subsystem Writers' 
Guide section/ Intraprocess Access Control (Rings)) and if the 
validation level is greater than Ring 1/ and only access names 
that contain the same project as the user/ and "SysDaemon" and 
"sys__control " projects will be allowed. If the replacement ACL 
is in error then no processing will be performed and the code 
error_tabl e_$ i nval i d__ pro ject_for_gate will be returned. 



© Copyright/ 1973/ Massachusetts Institute of Technology 
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hcs_$replace_di r_acl 



Subroutine Call 
2/15/73 



Name : hcs__$repl ace_di r_acl 



This subroutine replaces an entire Access Control List (ACL) 
for a directory with a user-provided ACL/ and can optionally add 
an entry for *.SysDaemon.* with mode sma to the new ACL, The 
dir__ acl structure described in hcs_$add_di r_acl _en tries is used 
by this subroutine. 



Usa^e 



declare hcs_$rep1ace_di r_ acl entry (char(*), chart*), ptr, 
fixed bin, bit(l), fixed bin(35)); 

call hcs_$repl ace_di r_acl (dirname, ename, acl_ptr, 
acl_count, no_sysdaemon_sw, code); 



1) dirname 

2) ename 

3) acl_ptr 
k) acl__count 

5) no_sysdaemon__sw 



is the path name of the directory superior to 
the one in question. (Input) 

is the entry name of the directory in 
question. (Input) 

points to a user-supplied dir_acl structure 
that is to replace the current ACL. (Input) 



is the number of entries 
structure. (Input) 



i n 



the dir_acl 



6) code 
Note 



if "0"b, then a *.SysDaemon. * sma entry will 
be put on the directory's ACL after the 
existing ACL has been deleted and before the 
user-supplied dir__acl entries are added; if 
"l"b, then only the user-supplied dir_acl 
will replace the existing ACL. (Input) 

is a standard status code. (Output) 



If acl_count is 
and only the action 
performed (if any). 
zero, processing of 

bottom, allowing later 



zero then the existing ACL will be deleted 
indicated by no_sysdaemon_sw will be 
In the case when acl__count is greater than 
the dir__acl entries is performed top to 

entries to overwrite previous ones if the 



access_name parts are identical. 
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hcs_$set_bc 



Subrout i ne Cal 1 
3/19/73 



Name ; hcs_$set_bc 

This subroutine sets the bit count of a segment in the 
storage system / given a path name. It also sets that segment's 
bit count author to be the user who called it. 

Usage 

declare hcs_$set_ be entry (char(*), char(*), 
fixed binUk), fixed bin(35)); 

call hcs_$set_bc (dirname, ename, bit_count, code); 

1) dirname is the directory name of the segment whose bit 

count is to be changed. (Input) 

2) ename is the entry name of the segment whose bit count 

is to be changed. (Input) 

3) bit_count is the new bit count of the segment. (Input) 

h) code is a standard storage system status code. 

(Output) 

Notes 

The user must have write permission with respect to the 
segment, but does not need write permission with respect to the 
parent directory. 

The subroutine hcs_$set_bc_seg performs the same function, 
when a pointer to the segment is provided rather than a path 
name. 
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hcs_$ se t__ bc_seg 



Subroutine Call 
3/19/73 



Name : hcs_$set_bc_seg 

This subroutine sets the bit count of a segment in the 
storage system, given the pointer to the segment. It also sets 
that segment's bit count author to be the user who called it. 

usage 

declare hcs_$set_bc_seg entry (ptr, fixed bin(2iO, 
fixed bin(35)); 

call hcs_$set_bc_seg (segptr, bitcount, code); 

1) segptr is a pointer to the segment whose bit count is to be 

changed. (Input) 

2) bitcount is the new bit count of the segment. (Input) 

3) code is a standard storage system status code. (Output) 
Note 

The user must have write permission with respect to the 
segment, but does not need write permission with respect to the 
parent directory. 

The subroutine hcs__$set_bc performs the same function, when 
provided with a path name of a segment rather than the pointer. 
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hcs_$star_ 



Subroutine Call 
U/2/73 



Name ; hcs_$star_ 

This subroutine is the star convention handler for the 
storage system. (See The Star Convent ion in the MPM Reference 
Guide section/ Constructing and Interpreting Names.) It is 
called with a directory name, and an entry name containing 
components which may be * or **. The directory is searched for 
all entries which match the given entry name. Information about 
these entries is returned in a structure. If the entry name is 
**, information on all entries in the directory is returned. 

Status permission is required with respect to the directory 
to be searched. 



The main entry returns the storage system type and all names 
which match the given entry name. (See hcs_$star_J i st_ below to 
obtain more information about each entry.) 



Usage 



declare hcs_$star_ entry (char(*)/ char(*)/ fixed bin(2), 
ptr, fixed bin, ptr, ptr, fixed bin(35)); 

call hcs_$star_ (dirname, star__name/ select_sw/ 
areap/ ecount/ eptr, nptr, code); 



1) dirname 

2) star__name 

3) select_sw 



k) areap 



5) ecount 



is the path name of the directory to be searched. 
( Input) 

is the entry name which may contain asterisks. 
(Input) 

- 1 if information is to be returned about link 
entries only; 

■ 2 if information is to be returned about segment 
entries only; 

=3 if information is to be returned about all 
entries. (Input) 

is a pointer to the area in which information is 
to be returned. If the pointer is null/ ecount is 
set to the total number of selected entries. See 

Notes immediately below. (Input) 

is a count of the number of entries which match 
the entry name. (Output) 
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6) eptr 



7) nptr 



8) code 



Notes 



is a pointer to the allocated structure in which 
information on each entry is returned. 



is a pointer to 
entry names 
s ta r__name. 



of all the 
which match 



the allocated array 
s in this directory which match 
See Notes immediately below. (Output) 

status code. See 



is a standard storage system 
Status Codes below. (Output) 



Even if areap is null, ecount is set to the total number of 
entries in the directory which match star_name. The setting of 
select_sw determines whether ecount is the total number of link 
entries, the total number of segment entries or the total number 
of all entries. 

If areap is not null, the following structure is allocated 
in the user-supplied area: 

declare 1 entries (ecount) aligned based (eptr), 
(2 type bi t(2), 
2 nnames bit (16), 
2 nindex bit(18)) unaligned; 



1) type 



2) nnames 

3) nindex 



specifies the storage system type of entry: 

0 ( l, 00 ,l b) = link, 

1 ("01%) ■ nondi rectory segment, 

2 ("10 n b) - directory segment. 

specifies the number of names for this entry which 
match star_name. 

specifies the offset in the array of names 
(pointed to by nptr) for the first name returned 
for this entry. 



All of the names which are returned for any one entry are 
stored consecutively in an array of all the names, allocated in 
the user-specified area. The first name for any one entry begins 
at the offset nindex in the array. 

declare names ( total_names ) char(32) aligned based (nptr); 
where total_names is the total number of names returned. 



It should be noted that the user must provide an area large 
enough for this subroutine to store the requested information. 
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Entry ; hcs__$star_1 i s t_ 



This entry returns more information about the selected 
entr i es . 



Usage 



declare hcs_$star_l i st_ entry (char(*), char(*) / 

fixed bin(3)/ ptr, fixed bin, fixed bin, ptr, ptr, 
fixed bin(35)); 

call hcs_$star_l i st_ (dirname, star_name, select_sw, 
areaP/ seg_count, link_count, eptr, nptr, code); 



1) dirname 

2) star_name 

3) select sw 



k) areap 



5) seg_count 

6) 1 i nk_count 

7) eptr 



i s as above. ( I npu t) 
is as above. (Input) 

=1 if information is 
entries only; 



to be returned about link 



=2 if information is to be returned about segment 
entries only; 



=3 if information 
entr i es ; 



is to be returned about all 



=5 if information is to be returned about link 
entries only, including the path name 
associated with each link entry; 

-7 if information is to be returned about all 
entries, including the path name associcated 
with each link entry. (Input) 

is a pointer to the area in which information is 
to be returned. If the pointer is null, seg_count 
and link_count are set to the total number of 
selected entries. See Notes immediately below. 
( I nput ) 

is a count of the number of segments and 
directories which match the entry name. (Output) 

is a count of the number of links which match the 
entry name. (Output) 

is as above. (Output) 
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8) nptr is a pointer to the allocated array in which 

selected entry names and path names associated 
with link entries are stored. (Output) 

9) code is as above. (Output) 
Notes 

Even if areap is null/ seg_count is set to the total number 
of segments and directories which match star_name, if information 
on segments is requested. If information on links is requested, 
link_count is the total number of links which match star_name. 

The following structure is allocated in the user-supplied 
area, if areap is not null: 

declare entries (count) bitd** 1 *) aligned based (eptr); 



where count ■ seg_count + link_count. 



For each unit of the array, one of two structures will be 
found. Which structure should be used may be determined by the 
type item which is located at the base of each structure. It 
should be noted that the first three items in each structure are 
identical to the structure returned by hcs__$star__. 

The following structure is used if the entry is a segment or 
a directory: 



1) type 

2) nname 

3) nindex 
k) dtm 

5) dtu 



declare 1 branches aligned based (eptr), 

(2 type bit(2), 

2 nname bi t( 16), 

2 nindex bit(18), 

2 dtm bit(36), 
2 dtu bit(36)^ 

2 mode bit(5), 

2 pad bit(13), 

2 records b i t ( 18 ) ) unaligned; 
is as above, 
is as above* 
is as above. 



is the date and time the segment or directory was 
last modified. 

is the date and time the segment or directory was 
last used. 
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6) mode 

7) pad 

8) records 



Is the current user's access to the segment or 
directory. See the MPM write-up of 

hcs_$append_branch for a description of modes. 

is unused space in this structure. 

is the number of 102U-word records of secondary 
storage which have been assigned to the segment or 
di rectory. 



The following structure is used if the entry is a link: 

declare 1 links aligned based (eptr), 
(2 type bit(2), 
2 nname bit (16), 
2 nindex bit(18) / 
2 dtm bit(36), 
2 dtd bit(36), 
2 pathname_len bit(18), 
2 pathname_i ndex b i t ( 18 ) ) unaligned; 



1) type 

2) nname 

3) nindex 
k) dtm 

5) dtd 

6) pathname_len 

7) pathname_i ndex 



is as above, 
is as above, 
is as above. 

is the date and time the link entry was 
modi f i ed. 

is the date and time the link entry was 
dumped. 

is the number of significant characters 
the pathname assocated with the link. 



last 



last 



i n 



is the offset in the array of names 
link pathname. See below. 



for the 



If the path name associated with each link entry was 
requested, the path name will be placed in the names array and 
will occupy six units of this array. The offset of the first 
unit is specified by pathname_i ndex in the links array. The 
length of the path name is given by pathname_len in the links 

array. 
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Status Codes 

If no match with star_name was found in the directory, code 
will be returned as error_tab1e_$nomatch. 

If star__name contained illegal syntax with respect to the 
star convention/ code will be returned as er ror_tab 1 e_$badstar . 

If the user did not provide enough space in the area to 
return all the requested information, code will be returned as 
error__tabl e_$notal loc. In this case the total number of entries 
(for hcs_$star_) or the total number of segments and the total 
number of links (for hcs_$star_J i s t_) will be returned, to 
provide an estimate of the space required. 
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Name ; hcs_ $status_ 



This subroutine consists of a number of hardcore/ 
user-callable/ storage system entry points which return various 
items of information about a specified hierarchy entry. 

The main entry point (hcs_$status_) returns the most often 
needed information about a specified entry. (See 
hcs_ $status__long below.) 



Usage 



declare hcs_$status_ entry (char(*), char(*), fixed bin(l), 
ptr, ptr, fixed bin(35)); 

call hcs_$status_ (dirname, entry, chase, eptr, nareap, 
code); 



1) dirname 

2) entry 

3) chase 



is the directory portion of the path name of 
entry in question. (Input) 

is the entry name portion of the path name of 
entry in question. (input) 



=0: 



is a link, return 



the 
the 
1 ink 



k) eptr 

5) nareap 

6) code 
Notes 



if the entry 
information; 

=1: if the entry is a link, return information 
about the entry to which it points. (Input) 

is a pointer to the structure in which information 
is returned. See Notes immediately below. 
(Input) 

is a pointer to the area in which names are 
returned. If the pointer is null, no names are 
returned. See Notes Immediately below. (Input) 



is a storage system status code. 
Requirements below. (Output) 



See Access 



The argument eptr points to the following structure if the 
entry is a segment or directory: 
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declare 1 branch based (eDtr) aligned, 
(2 type bit<2>, 
2 nnames bit(16), 
2 nrp bit(18) / 
2 dtm bit(36) / 
2 dtu bit(36), 
2 mode bi t(5)^. 
2 padl bit(13), 
2 records bit(18)) unaligned; 



1) type 



2) nnames 

3) nrp 

k) dtm 

5) dtu 

6) mode 

7) padl 

8) records 



specifies the type of entry: 

0 ("00"b) = link; 

1 ("01"b) = segment; 

2 ("10"b) = directory. 

specifies the number of names for this entry. 

is a relative pointer (relative to the base of the 
segment containing the user-specified free storage 
area) to an array of names. 



contains the date and time the 
modified. 

contains the date and time the 
used. 



segment was last 
segment was last 



contains the mode of the segment with respect to 
the current user. See the MPM write-up of 
hcs_$append_branch for a description of modes. 

is unused space in this structure. 

contains the number of 1024-word records of 
secondary storage which has been assigned to the 
segment. 



The argument eptr points to the following structure 
entry is a 1 ink: 

declare 1 link based (eptr) aligned, 
(2 type bit(2), 
2 nnames bit (16), 
2 nrp bit(18), 
2 dtem bit(36), 
2 dtd bit(36), 
2 pnl bit(18), 
2 pnrp bit(18)) unaligned; 



if the 
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1) type 



as above. 



2) nnames 



as above. 



3) nrp 



as above. 



k) dtem 



contains the date and time the link was last 
modified. 



5) dtd 



contains the date and time the link was last 
dumped. 



6) pnl 



specified the length in characters of the link 
path name. 



7) pnrp 



is a relative pointer (relative to the base of 
the segment containing the user-specified free 
storage area) to the link path name. 



Note that the user must provide the storage space required 
by the above structures. The status entry point merely fills 
them in. 

If nareap is not null, entry names are returned in the 
following structure allocated in the user-specified area. 

declare names (nnames) char(32) aligned based (np); 

where np = ptr (nareap, eptr->entry.nrp) . 

The first name in this array is defined as the primary name 
of the entry. 

Link path names are returned in the following structure 
allocated in the user-specified area. 

declare pathname char(pnl) aligned based (lp); 

where lp = ptr (nareap, eptr->l ink. nrp); 

Note that the user allocates the area and it must be large 
enough to accommodate a reasonable number of names. 

Access Requirements 

The user must have status permission on the parent directory 
to obtain complete information. 
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If the user lacks status permission but does have non-null 
access to a segment/ the following per-segment attributes may be 
returned: type, effective access/ bit count/ records and current 
length. In this instance if the entry point hcs__$status_ or 
hcs_$status__l ong is called/ the status code 

error__table__ $no__ s__pe rm i s s i on is returned to indicate that 
incomplete information has been returned. 

Entrv : hcs_$status_minf 

This subroutine returns the bit count and entry type given a 
directory and entry name. The access required to use this 
subroutine is status permission on the directory or non-null 
access to the entry. 



Usage 

declare hcs_$status__minf entry (char(*)/ char(*)/ fixed 

bin(l)/ fixed bin(2)/ fixed bin(2U)/ fixed b!n(35)>; 

call hcs_$status_minf (dirname, entry/ chase/ type/ bitcnt/ 
code) ; 



1) dirname 

2) entry 

3) chase 
k) type 



5) bitcnt 

6 ) code 



is as above. (Input) 
is as above. (Input) 
is as above. (Input) 
specifies the type of entry: 

0 = link; 

1 = segment; 

2 = directory. (Output) 
is the bit count. (Output) 
is as above. (Output) 



Entrv : hcs_$status_mins 

This subroutine returns the bit count and entry type given a 
pointer to the segment. The access required to use this 
subroutine is status permission on the directory or non-null 
access on the segment. 



Usage 



declare hcs__$status_mi ns entry (ptr, fixed bin(2)/ 
fixed bin(2i;)/ fixed bin(35)): 
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call hcs_$s tatus_mi ns (segptr, type^ b • tent > code); 



1) segptr is a pointer to the segment about which 

information is desired. (input) 

2) type is as above. (Output) 

3) bitcnt is as above. (Output) 

k) code is as above. (Output) 

Entrv : hcs_ $status_long 

This subroutine returns most user-accessible information 
about a specified entry. The access required to use this 
subroutine is the same as that required by hcs_$status_ and 
described in Access Reaui rements above. 

Msaee 

declare hcs_$status_long entry (char(*), char(*), 
fixed bind), ptr, ptr, fixed bin(35)); 

call hcs_$status_long (dirname, entry, chase, eptr, nareap, 
code ) ; 

Arguments are as above. 

Notes 

The argument eptr points to the same structure as before if 
the entry is a link. It points to the following structure if the 
entry is a segment or directory: 

declare 1 branch based (eptr) aligned, 
(2 type bit(2), 
2 nnames bit (16), 
2 nrp bit(18), 
2 dtm bit(36), 
2 dtu bit(36), 
2 mode bit(5), 
2 padl bit(13), 
2 records bit(18), 
2 dtd bit(36), 
2 dtem bit(36), 
2 pad2 bit(36), 
2 curlen bit(12), 
2 bitcnt bit(2U), 
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13) bitcnt 

Ik) did 

15) pad3 

16) copysw 

17) padU 

18) rbs 

19) uid 



2 pad3 bitU), 

2 copysw bit (9)/ 

2 pad** bit(9), 

2 rbs (0:2) bit(6), 

2 uid but(36)) unaligned; 



1- 


8) 


are as described above in the 
segments and directories returned by 


structure for 
hcs_$status_. 


9) 


dtd 


is the date and time the segment was 


last dumped. 


10) 


dtem 


is the date and time the branch was 


last modified. 


11) 


pad2 


is unused space in this structure. 




12) 


cur 1 en 


is the current length of the segment 


in units of 



1024-word records. 

is the bit count associated with the segment. 

specifies the secondary storage device (if any) on 
which the segment currently resides. 

is unused space in this structure. 

contains the setting of the segment copy switch. 

is unused space in this structure. 

contains the ring brackets of the segment. 

is the segment unique identifier. 
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Name : hcs_$ termi nate_f i 1 e 

This subroutine, given the path name of a segment in the 
current process, removes all the reference names of that segment 
and then removes the segment from the address space of the 
process. For a discussion of reference names, see the MPM 
Reference Guide section, Contructing and Interpreting Names. 

Usage 

declare hcs_$ termi nate_f i 1 e entry (char(*), char(*), 
fixed bin(l), fixed bin(35)); 

call hcs_$ termi nate_fi le (di rename, entry_name, rsw, code); 

1) di rename is the directory portion of the path name of the 

segment in question. (Input) 

2) entry__name is the entry name portion of the path name of the 

segment in question. (Input) 

3) rsw is the reserved segment switch. If equal to 1, 

the segment number should be saved in the reserved 
segment list; if equal to 0, the segment number 
should not be saved. (Input) 

k) code is a standard storage system status code. 

(Output) 

Notes 

The subroutine hcs_$ termi nate__seg performs the same 
operation given a pointer to a segment instead of a path name; 
hcs_$termi nate_name and hcs_$ termi nate_noname terminate a single 
reference name. 

The subroutine term__ performs the same operation as 
hcs_$termi nate__f i 1 e. 

In fact, only those reference names are removed for which 
the ring level associated with the name is greater than or equal 
to the validation level of the process. If the user needs to 
concern himself with rings, he should refer to the MPM Subsystem 
Writers' Guide section, Intraprocess Access Control (Rings). 
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Name ; hcs__$termi nate_jiame 

This subroutine terminates one reference name from a 
segment. if it is the only reference name for that segment, the 
segment is removed from the address space of the process. For a 
discussion of reference names see the MPM Reference Guide 
section, Constructing and interpreting Names. 

Usage 

declare hcs_$terminate_name entry (char(*), fixed bin(35)); 
call hcs_$terminate_ name (ref_name, code); 

1) ref__name is the reference name to be terminated. (Input) 

2) code is a standard storage system status code. (Output) 
Not e 

The subroutine hcs_$terminate_noname terminates a null 
reference name from a specified segment; he s_$ terminated i 1 e and 
hcs_$termi nate_seg completely terminate a segment given its path 
name or segment number, respectively. 

The subroutine te rm_$ s i n g 1 e_r e f n ame performs the same 
operation as hcs_$termi nate_name. 
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Name : hcs_$ termi nate_noname 

This subroutine terminates a null reference name from the 
specified segment. If this is the segment's only reference name, 
the segment is removed from the address space of the process. 
This entry is used to clean up after initiating a segment by a 
null name; see also the MPM write-up for hcs_$ 1 n 1 1 i ate. For a 
discussion of reference names, see the MPM Reference Guide 
section/ Constructing and Interpreting Names. 

Usage 

declare hcs__$termi nate_noname entry (ptr, fixed bin(35)); 
call hcs__$ termi n at e_noname (segptr, code); 

1) segptr is a pointer to the segment in question. (Input) 

2) code is a standard storage system status code. 

(Output) 

Note 

The subroutine hcs_$ termi nate_name terminates a specified 
non-null reference name; hcs_$terminate_f i 1 e and 

hcs_$ termi nate_seg completely terminate a segment given its path 
name or segment number, respectively. 
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Name : hcs__$terminate_seg 



This subroutine/ given a pointer to a segment in the current 
process/ removes all the reference names of that segment and then 
removes the segment from the address space of the process. For a 
discussion of reference names/ see the MPM Reference Guide 
section/ Constructing and Interpreting Names. 



Usage 



declare hcs_$ termi nate__ seg entry (ptr/ fixed bin(l)/ 
fixed bin(35)); 

call hcs__$ termi nate_ seg (segptr/ rsw # code); 



1) segptr is a pointer to the segment to be terminated. 

(Input) 

2) rsw is the reserved segment switch. If equal to 1/ 

the segment number should be saved in the reserved 
segment list; if equal to 0, the segment number 
should not be saved. (Input) 



3) code is a standard storage .system status code 

(Output) 

Notes 



The subroutine hcs_$ term i nate_.fi le performs the same 
operation given the path name of a segment instead of a pointer; 
hcs_$ termi nate_name and hcs_$termi nate_noname terminate a single 
reference name. 

The subroutine term_$segptr performs the same operation as 
hcs__$ termi nate__seg. 

In fact/ only those reference names are removed for which 
the ring level associated with the name is greater than or equal 
to the validation level of the process. If the user needs to 
concern himself with rings/ he should refer to the MPM Subsystem 
Writer's Guide section/ Intraprocess Access Control (Rings). 
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Name : hcs__$ truncate_f i 1 e 

This subroutine/ given a pathname/ truncates a segment to a 
specified length. If the segment is already shorter than the 
specified length/ no truncation is done. The effect of 
truncating a segment is to store zeros in the words beyond the 
specified length. 

Usage 

declare hcs_$ truncate.fi 1 e entry (char(*)/ char(*)/ 
fixed bin/ fixed bin(35)); 

call hcs_$ truncate__f i le (dirname/ ename, length/ code); 

1) dirname is the directory portion of the path name of the 

segment in question. (Input) 

2) ename is the entry portion of the path name of the 

segment in question. (Input) 

3) length is the new length (decimal) of the segment in 

words. (Input) 

4) code is a standard storage system error code. (Output) 
Notes 

The subroutine hcs_$ truncate_seg performs the same function 
when given a pointer to the segment instead of the path name. 
See also the restrictions discussed in that write-up under Notes . 
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Name : hcs_$ truncate_seg 

This subroutine, given a pointer, truncates a segment to a 
specified length. If the segment is already shorter than the 
specified length, no truncation is done. The effect of 
truncating a segment is to store zeros in the words beyond the 
specified length. 

Usage 

declare hcs_$ truncate_seg entry (ptr, fixed bin, 
fixed bin(35)); 

call hcs_$ truncate_seg (segptr, length, code); 

1) segptr is a pointer to the segment to be truncated. Only 

the segment number portion of the pointer is used. 
(Input) 

2) length is the new length (decimal) of the segment in words. 

(Input) 

3) code is a standard storage system status code. (Output) 
Notes 

The write attribute is required with respect to the segment. 
A directory may not be truncated. 

The implementation is such that pages will be thrown away 
starting from the next page after the word number length and the 
remainder of the last page will be zeroed. 

The subroutine hcs__$ truncate_f i le performs the same function 
when given the pathname of the segment instead of the pointer. 
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Name : ioa_ 

This procedure is used for formatting, according to a 
control string (see Notes ) . character strings, fixed binary 
numbers, floating numbers, and pointers into complete character 
string form. Entry points are provided that write the formatted 
string out on the stream "user^output", on a specified stream, or 
which return the expanded string. The expanded string cannot 
exceed 256 characters when the line is to be written out. 

Since this procedure can be called with a varying number of 
arguments, it is not permissible to include a parameter attribute 
list in the declaration of the various entry points. 

Entry : ioa_ 

The ioa_ entry reformats the input data and writes the 
resultant character string out on the stream "use^output" with a 
new line character added at the end. 

Usage 

declare ioa_ entry options (variable); 

call ioa_ (control_str i ng, argl, arga); 

1) control_str ing is a character string (char(*)) specifying 

the output format for the data. See Notes 
below. (Input) 

2) argjL is the variable to be placed in the j_th 

argument position of the control string. 
(Input) 

Entrv: ioa_$nnl 

This entry is identical to ioa_ except that no new line 
character is added. 

Usage 

declare ioa_$nnl entry options (variable); 

call ioa_$nn1 (control_str i ng, argl, •••/ argn); 

Arguments are as above. 



(c) Copyright, 1973, Massachusetts institute of Technology 

and Honeywell Information Systems Inc. 



ioa. 



, MULT ICS PROGRAMMERS 1 MANUAL 



Page 2 



Entry * Ioa $ioa stream 

This entry reformats the input data, appends a new line 
character/ and writes the resultant character string out on the 
specified output stream. 

Usage 

declare ioa_$ ioa_stream entry options (variable); 

call ioa_$ ?oa_st ream (stream_name, control_str ing, 
argl, argn); 

1) stream__name is the name (char(*)) of the output stream 

des i red. ( I nput ) 

2) is as above. (Input) 

3) is as above. (Input) 

Entrv : ioa__$ ioa_st ream_nnl 

This entry is identical to ioa__ $ ioa_stream except that no 
new line character is added. 

Usage 

declare ioa_$ ioa_st ream_nnl entry options (variable); 

call ioa_$ ioa__st ream__nnl (stream_name, control__str ing, 
arg^ .../ argn); 

Arguments are as above. 

Entry; ioa_$rs 

This entry reformats the data but instead of writing the 
string out/ it returns the new expanded string as well as the 
significant length of the new string/ in characters. Note that 
the returned string argument should be declared large enough to 
allow for expansion extremes. It can be a varying or nonvarying 
string/ aligned or unaligned. If it is nonvarying/ it is padded 
with blanks if the expanded string does not completely fill it, 
unless the entries ioa_$rsnp or ioa_$rsnpnnl were called (see 
below). Expansion stops when the end of the returned string 
argument is reached. 
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Usage 



declare ioa_$rs entry options (variable); 



call ioa_$rs (contro1_str i ng, return_str i ng, length/ 
argi/ . ../ arga); 



1) control_str I ng 



is as above. (input) 



2) return_str i ng 



is the returned formatted string (char(*)). 
See Notes below. (Output) 



3) length 



is the number (fixed bin) of significant 
characters in return_str i ng. (Output) 



h) argi 



i s as above. ( I nput ) 



Entrv : ioa_$rsnnl 

This entry is identical to ioa_$rs except that no new line 
character is added at the end. 

Usage 

declare ioa__$rsnnl entry options (variable); 

call ioa_$rsnnl (control_str i ng/ return__str i ng/ len, 
argl/ .../ arga); 

Arguments are as above. 

Entrv: ioa_$rsnp 

This entry is identical to ioa_$rs except that the end of 
return_str ing is not padded with blanks. 

Usage 

declare ioa_ $rsnp entry options (variable); 

call ioa_$rsnp (control_str i ng, return__str ing/ len, 
argi/ .. ./ argn); 

Arguments are as above. 
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Entry: ioa_$rsnpnnl 

This entry is identical to ioa_$rsnp except no new line 
character is added at the end. 

Us a, p;e 

declare ioa_$rsnpnnl entry options (variable); 

call ioa_$rsnpnnl (control_str i ng, return_str i ng, len, 
argl, . . arga); 

Arguments are as above. 

Notes 

All entries require a control string argument. This is a 
character string which may or may not contain control characters 
within it. If no control characters occur/ the string is merely 
returned at the rs entry points or written out at the other entry 
points. If control characters exist, they govern the conversion 
of successive additional arguments which are expanded into the 
appropriate characters and inserted into the resultant string. 
The control characters are indicated by the circumflex character 
(~) and may take an optional field width (n or 4). The 
possibi 1 i ties are: 

A d or And 

A o or ^no 

A f or -Mi.^f 
or ^af 
or *.±f 

A e or ^ie 

A a or A na 
A P 

*w or A aw 
-I 

* I or 



decimal 

octal 

floating 

exponential 
ASCI I 
poi nter 

f ul 1 word octal 

insert form feed (new page) character 
insert new line character 
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A - or a a- Insert horizontal tab 

A x or a jqx insert blank character 
A A acc string 

A R insert red ribbon shift character 

A B insert black ribbon shift character 

AA insert circumflex character 



where a expresses the field width, a can be a decimal integer 
constant or the letter v. if a is the letter v, the next argi 
specifies the field width and the following argument/ arg( i +1 ) , 
is the datum to be converted, if required, i is a decimal 
integer specifying the number of digits to the right of the 
decimal point. 

* d assumes a fixed binary input and converts this to 
decimal. If a number appears between the circumflex and 
the d, the decimal character string is placed right 
justified in a field as wide as the specified number and 
padded with blanks. 

A o assumes a fixed binary input and converts it to octal 
form. It is similar to d. 

A f assumes a floating input. The following cases can 
occur: 

A f An attempt is made to output nine significant 

digits. If the field width exceeds 13, the 
number is converted to exponential form. The 
field does not contain any blanks. 

A af The decimal point is placed at the extreme 

right in the field and no fraction part 
appears. High-order zeros are converted into 
blanks. 

A .olf The minimum field width is d+2 to accommodate a 
fraction part si digits long and the decimal 
point. If necessary, the field is extended to 
accommodate the integer part or minus sign or 
both. 
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A n m df I f the number cannot be accoiuncdated in this 
field, it is converted to exponential form. 
High-order zeroes are converted into blanks. 

A e assumes a floating input. ii, if not specified, is 
assumed to be eight. The number is converted to the 
following format: 

±. x x x e±y y 

12 d 1 2 

^a (ASCII) assumes a varying or nonvarying character string 
as input. If there is no field width, trailing blanks 
are stripped. If the field width is specified, the 
string is left adjusted within the field and padded with 
trailing blanks up to the specified field width. If the 
length of the string after trailing blanks have been 
removed is greater than the specified field size, the 
field size is ignored. 

A p assumes a pointer as input and expands i t to a character 
string of the form "276 | 13640". If a bit offset is 
present, it is printed as a decimal number immediately 
following the word offset in the form "276 1 13640(27)". 
No field width option is accepted. 

A w (word) assumes a fixed binary number as input and 
converts i t to a 12-character octal number padded on the 
left with leading zeros. The field width is accepted, 
but is ignored if less than 12. 

A | causes a form feed (new page) character to be inserted 
into the expanded string. No field width is accepted. 

A / causes a new line character to be inserted into the 
expanded string, a specifies repetition. 

A - causes a horizontal tab character to be inserted into 
the expanded line, n specifies repetition. 

A x causes a blank character to be inserted into the 
expanded line, a specifies repetition. 

A A assumes that the current argument is a pointer to a 

character string in acc (ASCII Character with Count) 
format. The character string is inserted into the 
expanded line. No field width is accepted. 
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aa causes a circumflex character ( ) to be Inserted into 
the string. 

A R causes a red ribbon shift character to be inserted into 
the string. 

A B causes a black ribbon shift character to be inserted 
into the string. 

Any character other than those cited following a circumflex 
is ignored. To write a bit string out, it should first be 
converted to fixed mode and then an octal format used. If a 
number does not fit in a specified field width, the field width 
is expanded so that the complete number is printed. 

If no arguments remain to be converted, the circumflex is 
merely copied into the output field. 

Examples 

1) call loa_ ("This is "a the third of *a", "Mon", "July"); 
Result: This is Mon the third of July. 

2) call ioa_ ("date *d/*d/*d, time A d: A d", 6, 20, 69, 

201U, 36); 

Result: date 6/20/69, time 2014:36 

3) call ioa_ ("overflow at A p", ptr); 
Result: overflow at 271|4671 

4) call ioa__ ( /v 6o A 14w^l4w / ^14w", no, wordl, word2, word3); 
Result: 014100 014114214300 00000014000 111000101104 

5) call ioa_ ("*a"); 
Result: a 

6) call ioa_ ( "a= A f A x A . 3f ", a, a); 
Result: a=123. 456789 123.457 
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Mama: ios_ 

This write-up describes the generalized I/O system function 
calls. The reader is cautioned that the descriptions contained 
in this document state the general purpose of each call as put 
forth in the I/O system specifications and that the result of a 
particular call to a device is dependent on that device and its 
associated software. However/ any deviations of a particular 
device from the specifications stated here are enumerated in the 
MPM write-up describing the software for that device. These 
descriptions are labeled I/O System Interface Modules (lOSIMs). 
The reader should also refer to the specific I OS I M write-ups to 
see which I/O system function calls are implemented for that 
device since only a 1 imi ted number of these calls are usually 
implemented for each device. Users should also see the MPM 
Reference Guide section/ Input and Output Facilities/ for further 
i nformat ion. 

Generic Arguments 

Rather than reproduce the descriptions of arguments that are 
common to several function calls under the description of each 
function call/ they are given here. 

1) stream^ name is a string of 32 characters or less 

that identifies the stream upon which 
this call is to be performed. A stream 
usually identifies a particular device 
and the control software, the Device 
Interface Module (DIM)/ for that device. 
(Input) 

2) type is a string of 32 characters or less 

that identifies the control software/ 
the DIM/ for a type of device. A list 
of system supported types is given in 
the MPM Reference Guide section/ 
Available Input and Output Facilities/ 
and each type is described in the MPM 
Subroutines section as an I0SIM. 
(Input) 

3) devi ce/stream_name is the identifier of a particular 

device/ pseudodevi ce/ or stream name 
upon which an I/O operation can be 
performed. (Input) 

k) mode describes characteristics related to an 

attachment (e.g./ readable, writeable/ 
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The modes perm! tted for 



5) status 



6) disposal 

7 ) gmode 



8) smode 



9) limit 



10) oldstatus 



11) request 



12) argptr 



13) element_size 



Ik) workspace 



particular device type are described in 
the 10SIM write-up for that device type. 
(Input) 

is a bit string returned by an I/O call 
containing information about the success 
of that call, (See the MPM Reference 
Guide section, Use of the Input and 
Output System.) This bit string must be 
aligned. (Output) 



indicates special action 
when a device is detached. 



to be taken 
(Input) 



is a string of 128 characters or less 
containing an encoding of the mode of an 
attachment. The addition of new modes 
in the future could make the maximum 
length of gmode even greater. (Output) 

is the synchronization mode. The mode 
can be synchronous ("s") or asynchronous 
("a"). (Input) 

is the maximum number of elements of 
write-behind or read-ahead data 
permissible in asynchronous mode. 
(Input) 

is the status string of a previous 
transaction. This string must be 
aligned. (Input) 

is a special request to the I/O system. 
The requests appropriate to a device 
type are described in the I0SIM write-up 
for that device type. (Input) 

is a pointer to a data structure 
containing information relevant to a 
special request. (Input) 



is the current element size (i 
number of bits in an element) 
or write calls. (Input/Output) 



e., 
for 



the 
read 



is a pointer to the buffer space for 
data to be read into or written from. 
The buffer space must be aligned. 
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(Input) 



15) offset 

16) nelem 

17) nelemt 

18) nbreaks 

19) breaklist 



20) nreads 

21) readlist 

22) po i nter_name_l 



23) po i nter_ name_2 



is the number of elements from the 
beginning of the workspace at which to 
start reading or writing data. (Input) 

is the number of elements requested to 
be read or written. (input) 

is the number of elements actually read 
or written. (Output) 



is the number of break characters 
breaklist. (Input/Output) 



i n 



is an array of break characters. This 
is an unaligned bit string array each 
element of which is element__si ze bits 
long. (Input/Output) 

is the number of read delimiters in 
readlist. (Input/Output) 

is an array of read delimiters. This is 
an unaligned bit string array each 
element of which is element_size bits 
long. (Input/Output) 

is a string of 32 characters or less 
specifying a reference pointer that 
identifies a particular position in the 
data referred to by the stream (e.g., 
the write pointer points to the next 
element to be written). For a 
description of reference pointers, see 
the MPM Reference Guide section. Use of 
the Input and Output System. 
( Input/Output) 



is the same 
( Input/Output) 



as 



po i n te r__name_l . 



Entrv : ios__$wr i te_ptr 



The write_ptr call is a specialized form of the write call 
(see below). The number of elements specified by nelem in the 
buffer area pointed to by workspace starting at the element 
specified by offset is written on the stream ,f user_output" . 
Since the stream M user_output" is normally associated with the 
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user ! s terminal/ a write__ptr call usually results in the 
specified elements being typed on the user's terminal. The 
write_ptr call should be used in preference to the write call 
when writing on the stream "user_output" due to the greater 
efficiency of the write_ptr call. 

Usage 

declare i os_$wr i te_ptr entry (ptr, fixed bin, fixed bin); 
call ios_ $wr i te_ ptr (workspace, offset, nelem); 



Entrv : ios_$read_ptr 

The read__ptr call is a specialized form of the read call 
(see below). The number of elements specified by nelem are 
attempted to be read from the stream "user_j nput" into the buffer 
area pointed to by workspace. If a read delimiter is encountered 
as one of the elements being read, reading ceases with this 
element. Therefore, the number of elements read in is either 
nelem or up to the first read delimiter, whichever comes first, 
and this number is returned in nelemt. Since the stream 
"user_i nput" is normally associated with the user's terminal, a 
read__ptr call usually results in the specified elements being 
read from the terminal. The read_ptr call should be used in 
preference to the read call when reading from the stream 
"user_i nput" due to the greater efficiency of the read_ptr call. 

Usage 

declare ios_$read_pt r entry (ptr, fixed bin, fixed bin); 

call i os_$ read_ptr (workspace, nelem, nelemt); 

Entrv : ios__$write 

The write call attempts to write from the buffer area 
pointed to by workspace, starting offset elements from the 
beginning of the buffer area, the requested number (nelem) of 
elements onto the stream stream__name. The number of elements 
actually written is returned in nelemt and indications of the 
status of the transaction are returned in status. 

Usage 

declare ios_$write entry (char(*), ptr, fixed bin, 
fixed bin, fixed bin, bit(72) aligned); 
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call ios_$write (stream_name, workspace/ offset, nelem, 
nelemt, status); 

Entry : ios_$read 

The read call attempts to read Into the buffer area pointed 
to by workspace, starting offset elements from the beginning of 
the buffer area, the requested number (nelem) of elements from 
the stream stream_name. If a read delimiter is encountered as 
one of the elements being read, reading ceases with this element. 
Therefore, the number of elements read in is either nelem or up 
to the first read delimiter, whichever comes first, and this 
number is returned in nelemt. Indications of the status of the 
transaction are returned in the status argument. 

Usage 

declare ios_$read entry (char(*), ptr, fixed bin, 
fixed bin, fixed bin, b I t ( 72 ) aligned); 

call ios_$read (stream_name, workspace, offset, nelem, 
nelemt, status); 

Entry ; ios__$attach 

The attach call associates the given stream_ name with a 
device or stream name, devi ce/stream__name, as a particular type 
(DIM). All subsequent read or write operations performed upon 
the stream identified by stream__name result in data being 
transferred from or to the device or stream identified by 
devi ce/stream_name and this transfer is performed by the DIM 
(control software) identified by the type argument. This 
association remains in force until removed by a detach call (see 
below). The mode argument specifies how attributes of this 
attachment differ from the default. If mode is "", then the 
default attributes for the specified device are used. 

Usage 

declare ios_$attach entry (char(*), char(*), char(*), 
char(*), bit(72) aligned); 

call ios_$attach (stream__name, type, devi ce/stream_name, 
mode, status); 

Entry : ios_$detach 

The detach call deletes all associations established by an 
attach call between stream__name and devi ce/stream_name. If 
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are deleted. The disposal argument indicates any special action 
to be taken on detachment. If disposal is "", the appropriate 
default action for the I OS I M involved is taken. 

Us a fie 

declare ios_$detach entry (char(*), char(*) / char(*)/ 
bit(72) aligned); 

call ios_$detach (stream_name, dev i ce/stream_jiame, 
disposal/ status); 

Entry: i os_$ resetwr i te 

The resetwrite call is used to delete unused write-behind 
data collected by the I/O system as a result of write-behind 
associated with the stream stream_name. 

Usage 

declare ios__$ resetwr i te entry (char(*), bi t(72) aligned); 

call ios_$resetwr i te (stream_jiame, status); 

Entry: ios__$ reset read 

The resetread call is used to delete unused read-ahead data 
collected by the I/O system as a result of read-ahead associated 
with the stream stream_name. 

Usage 

declare ios_$resetread entry (char(*), bit(72) aligned); 

call i os_$ reset read ( st ream_name, status); 

Entry : ios_$abort 

The abort call causes all outstanding transactions on the 
stream stream_ name to be aborted. The oldstatus argument should 
be set to M,l b. 

Usage 

declare ios_$abort entry (char(*), bit(72) aligned, 
bi t(72) al igned); 

call ios_$abort (stream_name, oldstatus, status); 
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Entry: ios_$order 

The order call is used to issue a specialized request on the 
stream stream_name. The argptr argument points to a data 
structure containing arguments relevant to the particular 
request. Allowable requests depend upon the type (the DIM) 
associated with the steam stream_name. The order requests 
appropriate to a device type are described in the I0SIM write-up 
for that device type. The order call is used to perform 
specialized I/O operations when no generalized I/O call is 
available. Note that although argptr is an input argument, the 
structure to which it points can contain both input and output 
i nformation. 

Usage 

declare ios__$order entry (char(*), char(*), ptr, b 1 1 ( 72 ) 
al i gned); 

call ios__$order (stream_name, request/ argptr, status); 

Entry : ios_$getsize 

The getsize call returns the current element size associated 
with the stream stream_name. 

Usage 

declare ios„$getsize entry (char(*), fixed bin, 
bit(72) al igned); 

call ios__$gets ize (stream_name, element_si ze, status); 
Entrv : ios_$setsize 

The setsize call sets the element size for subsequent calls 
on the stream stream_name. 

Usage 

declare ios_$setsize entry (char(*), fixed bin, 
bit(72) aligned); 

call ios_$setsize (stream__name, el ement_s i ze, status); 

Entrv : ios_$getdel im 

The getdelim call returns the read delimiters and breaks 
currently in effect on the stream stream_name. The breaks are 
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to the number of breaks. The read delimiters are returned as an 
array of elements in readlist and nreads is set to the number of 
read delimiters. If either array is not large enough to contain 
all of the returned delimiters or breaks, as many as possible are 
returned. 

Usage 

declare ios_$getdel im entry (char(*), fixed bin, 
(*) bit (element_si ze), fixed bin, 
(*) bit (element_size), bit(72) aligned); 

call ios_$getdel im (stream_name, nbreaks, breaklist, 
nreads, readlist, status); 

Entrv : ios_$setdel im 

The setdelim call establishes elements to delimit data read 
by subsequent read calls on the stream stream_name. The argument 
breaklist is an array of breaks (containing nbreak elements), 
each serving simultaneously as an interrupt, canonical izat ion and 
erase-and-ki 1 1 delimiter. Breaks are meaningful only on 
character oriented devices. The argument readlist is an array of 
read delimiters (containing nreads elements). Read delimiters 
cause subsequent read calls to cease reading at the first read 
delimiter element. The new delimiters established by this call 
are in effect until superseded by a subsequent setdelim call. 

Usage 

declare ios_$setdel im entry (char(*), fixed bin, 
(*) bit (element_si ze), fixed bin, 
(*) bit (element_size), bit(72) aligned); 

call ios__$setdel im (st ream_name, nbreaks, breaklist, 
nreads, readlist, status); 

Entry; ios_$seek 

The seek call sets the reference pointer specified by 
poi nter__name_l to the value of the pointer specified by 
pointer_name_2 plus the value of a signed offsets offset, 
poi nterjiame__l and poi nter_name_ 2 can be "read", "write", "last", 

or "bound". The read pointer indicates the next element to be 
read, the write pointer the next element to be written, the first 
pointer the first element of data associated with this stream, 
the last pointer the last element of data, and the bound pointer 
the element beyond which data cannot grow. The seek call is used 
to truncate; e.g., call ios_$seek (stream_name, "last", "last", 
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-40/ status); or to set the bound of data; e.g./ call ios_$seek 
(stream_name/ "bound 11 / "last"/ 21, status); in addition to its 
more traditional usage involving the read and write pointer; 
e.g./ call ios_$seek (stream = name/ "read"/ "write"/ -2, 
status);. The read and write pointers are also set as a result 
of read and write calls/ respectively. All relative offsets 
between reference pointers are in terms of numbers of elements. 

Usage 

declare ios_$seek entry (char(*)/ char(*)/ char(*)/ 
fixed bin/ bit(72) aligned); 

call ios_$seek (st ream_name/ poi nter_name_l/ 
pointer_name_2/ offset/ status); 

Entrv : ios_$tell 

The tell call returns the value of the pointer specified by 
poi nter_name_l as an offset/ with respect to poi nter__name_2. The 
arguments poi nter_jiame_l/ poi nter_name_2/ and offset have the 
same meaning as in the seek call. As an example/ the call can be 
used to obtain the bound of the data by call ios__ $tell 
(stream^ name/ "bound"/ "first"/ offset/ status);. 

declare ios_$tell entry (char(*)/ char(*)/ char(*)/ 
fixed bin/ bit(72) aligned); 

call ios_$tell (stream_name/ po i nter_name_l/ 
poi nter_name_2/ offset/ status); 

Entrv : ios__$changemode 

The mode of an attachment describes certain characteristics 
related to the attachment (e.g./ readable/ writeable/ linear/ 
formatted/ etc.). The changemode call permits mode changes to be 
invoked for the given stream stream_name that modify the mode of 
the attachment. The gmode argument is set to the mode of the 
attachment prior to this call. 

Usage 

declare ios_$changemode entry (char(*)/ char(*)/ char(*)/ 
bit(72) aligned); 

call ios_$changemode (stream__name/ mode, gmode/ status); 
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En trv i i os $ readsync 

For the given stream_name, the readsync call sets the read 
synchronization mode, smode, of subsequent read calls. This mode 
is either synchronous or asynchronous. Synchrony implies that 
the read operation is performed in its entirety during a read 
call. Asynchrony implies that read-ahead is possible to the 
extent permitted by the limit argument/ which is the desired 
maximum number of elements which can be read ahead. The default 
mode is asynchronous. 



Usage 



declare ios_$ readsync entry (char(*), chard), fixed bin / 
bit(72) aligned); 



call ios__$ readsync (stream_name, smode, limit, status); 

Entry : ios_$wr i tesync 

For the given stream_name, the wri tesync call sets the write 
synchronization mode, smode, of subsequent write calls. The mode 
is either synchronous or asynchronous. Synchrony implies that 
the write operation is performed in its entirety during a write 
call. Asynchrony implies that write-behind is possible to the 
extent permitted by the limit argument, which is the desired 
maximum number of elements which can be written behind. The 
default mode is asynchronous. 



Usage 



declare ios__$wri tesync entry (char(*), chard), fixed bin, 
bit(72) al igned); 

call ios__$wri tesync (stream_name, smode, limit, status); 
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Name : match__star_name_ 

This procedure implements the Multics storage system star 
convention by comparing an entry name with a name containing 
stars or question marks (called a star name). Refer to the MPM 
Reference Guide section / Constructing and Interpreting Names, for 
a description of the star convention and a definition of 
acceptable star name formats. 

Usage, 

declare match_star_name_ entry (char(*), char(*), 
fixed bin(35)); 

call match_star_ name_ (entry_name, star__name, code); 

1) entry_name is the entry name to be compared with the star 

name. Trailing spaces in the entry name are 
ignored. (Input) 

2) star_name is the star name it is to be compared with. 

Trailing spaces in the star name are ignored. 
(Input) 

3) code is a status code that can have one of the values: 

0 the entry name matches the star name. 

e r ro r__ta b 1 e__$ noma t ch 

the entry name does not match the star name. 

error_table_$ bads tar 

the star name does not have an acceptable format. 
(Output) 

Notes 

Refer to the MPM write-up for the hcs„$star_ subroutine to 
see how to list the directory entries that match a given star 
name. 

Refer to the MPM write-up for the check__star_name_ 
subroutine to see how to validate a star name. 
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Name: move names 



This procedure moves all the entry names, except the one 
used to designate the original segment, from one segment to 
another. Name duplications are handled by nd_handler_. 



Usage 



declare move_names_ entry (char(*), char(*), char(*), 
char(*), char(*), bit(l) aligned, fixed bin(17)); 

call move_names__ (dlrl, enl, dir2, en2, caller, errsw, 
code) ; 



1) dlrl 

2) enl 

3) dir2 
k) en2 

5) caller 

6) errsw 



7) code 
Note 



is the directory in which the original segment is 
found, (Input) 

is a name on the original segment. (Input) 

is the target segment's directory, (Input) 

is a name already on the target segment. (Input) 

is the name of the calling procedure; it is used 
in calls to nd_handl er__. (Input) 

indicates which segment the error indicated by 
"code" occurred on; it is set to "0"b if the error 
was on the original segment and to "l M b if on the 
target. (Output) 

is a standard File System status code. 



If a name duplication occurs and the conflicting name is 
not deleted, then the code "error_tabl e_$namedup" is returned to 
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the caller. The names that occur after the conflicting name are 
processed. 



(END) 
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Name : nstd_ 



This procedure Is an I/O system Device Interface Module 
(DIM) used to control operation of magnetic tapes. (Note that 
this is the nonstandard £ape I)IM; Multics standard tapes are 
defined by and dealt with through the tape_ DIM.) The subroutine 
nstd_ is not directly called by a user program. Instead, the 
user provides the name nstd_ in a call to the I/O system attach 
entry. He then accomplishes the I/O operations by calling 
standard I/O system entry points which are independent of the 
interface module in use. Further information on the I/O system 
may be found in the MPM Reference Guide sections on Input and 
Output Facilities. Details on the I/O system call syntax may be 
found in the module description of ios__. This write-up explains 
how nstd_ interprets the standard I/O system calls. 

Usage 

call ios_$attach (stream, "nstd_", reel, mode, status); 



1) stream 



is the name of the 
(Input) 



I/O stream to be attached. 



2) "nstdj* 

3) reel 

k) mode 



5) status 



specifies the nonstandard tape DIM. (Input) 

is the reel identifying message which will be 
passed on to the operator in the mount message. 
(Input) 

is r for reading, and w for writing, or rw for 
reading and writing. If the mode is r, the mount 
message will specify no write ring. All other 
modes will cause the mount message to specify a 
write ring, (input) 

is a status indicator. See the section below on 
Returned Status. (Output) 



permj HQ System Calls 

The following I/O system calls are implemented by this DIM: 

attach 

changemode 

detach 

gets i ze 

order 

read 

wr i te 
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Order frequent? 

The following order requests are implemented by this DIM: 
binary 



bed 

nine 

back 
eof 

saved_ status 
er recount 



request_status 



forward_record 
forward_f i le 

backspace__f i le 



set hardware mode to binary (this is the 
default). 

set hardware mode to binary coded decimal 
(BCD). 

set hardware mode to nine track (the default 
is seven track). 

backspace one record. 

write end of file (EOF) . 

return last hardware status. The result will 
be written into the location pointed to by 
the pointer argument of the ios_$order call 
as bit(12) aligned. 

set error retry count. This is used to 
change the error retry count which has an 
initial value of 10 and which controls the 
number of times a tape operation encountering 
an error will be retried before being 
reflected to the caller. If the pointer 
argument of the ios_$order call is null, the 
error retry count will be set to 0 (i.e./ 
errors will be passed directly to the caller 
with no retry attempts). If the pointer 
argument is not null, it must point to a 
fixed bin(17) error count which is 
nonnegative and less than 100. 

issue a request status command to the tape 
controller. The status will be written into 
the location pointed to by the pointer 
argument of the ios_$order call as bit (12) 
al igned. 



forward space one record. 



forward space 
just past the 



to an EOF 
EOF mark. 



mark. The tape stops 



backward space to an EOF mark. The tape 
stops just before the EOF mark; i.e., a 
subsequent read will encounter the EOF mark. 
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erase 

high 

low 

protect 



erase tape. 

set high density (this is the default), 
set low density. 

set write inhibit regardless of the presence 
of a write permit ring in the tape reel. The 
tape unit will remain write inhibited until 
the tape is detached. 



unload rewind tape and unload (done automatically 

when the tape is detached). 

rewind rewind the tape to the load point. 

f ixed_record_length allow the DIM to operate asynchronously/ 

reading up to six physical records at a time. 
The pointer argument must point to a fixed 
bin(17) number indicating the record size. 
Subsequent read and write calls continue to 
pass one physical record. 



Returned Status 



The first half of the status string may contain either 
standard Multics status codes or hardware status. If the latter/ 
the first bit will be 1 and the rightmost 12 bits of the first 
half of the status string will hold hardware status as described 
in Table I below. 



Detaching 



When a tape is detached/ it will be rewound and unloaded and 
the drive will be freed for attachment. No other types of 
detachment are permitted. 



Element Size 

Only an element size of thirty-six is permitted. 
Buffer $i 2 e 

The maximum number of words which may be transmitted on a 
read or write call is 1632. 
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Statu? Code? 

The following status codes may be returned by nstd_: 

error_table_$bad_index 

e r ro r_ t ab 1 e_$ bu f f e r_b i g 

e r r o r_ t ab 1 e_$ I onma t 

e r ro r_tab 1 e_$ no_backspace 

e r ro r_t ab 1 e_$ no_de v i ce 

e r ror_tab 1 e_$ no t_a 1 1 ached 

error__table_$undef ined_order_request 

See also the MPM Reference Guide section / List of System 
Status Codes and Meanings, for more information. 

Notes 

All order requests and the changemode call reset the 
f i xed_record_length state after writing the current set of 
buffers, if any. The changemode call does not reposition the 
tape; it is the user's responsibility to do so. 
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Peripheral Subsystem Ready 
Write Protected 
Positioned on Leader 
Nine Track Tape Unit 

Device Busy 

Device Attention 
Write Inhibit 
No Such Tape Unit 
Tape Unit in Standby 
Tape Unit Check 
Blank Tape on Write 

Device Data Alert 

Transfer Timing Alert 
Blank Tape on Read 
Transmission Parity Alert 
Lateral Parity Alert 
Longitudinal Parity Alert 
End of Tape (EOT) Mark 
Bit During Erase 

End of File 

EOF Mark (Seven Track) 
EOF Mark (Nine Track) 
Data Alert Condition 
Single Character Record 

Command Reject 

Invalid Operation Code 
invalid Device Code 
Parity on I/O 
Positioned on Leader 
Read After Write 
Nine Track Error 

Program Load Termination 

Peripheral Subsystem Busy 
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e 1 

Major Status $ubgtatus 
000000 

000XX1 
000X1X 
0001XX 

000001 
000010 

0XXXX1 
0XXX1X 
0XX1XX 
0X1XXX 
01XXXX 

000011 

000001 
XXXX1X 
XXX1XX 
XX1XXX 
X1XXXX 
1XXXXX 
XXXX11 

000100 

001111 
011100 

111111 

XXXXXX 

000101 

XXXXX1 
XXXX1X 
XXX1XX 
XX1XXX 
X1XXXX 
1XXXXX 

000111 
001000 
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Name : object_info_ 

This procedure returns structural and identifying 
information extracted from an object segment. It has three entry 
points returning progressively larger increments of information. 
All three entry points have identical calling sequences/ the only 
distinction being the amount of information returned in the info 
structure described below. 

Fnt ry : ob ject_i nf o_$br i ef 

This entry only returns the structural information necessary 
in order to be able to locate the object's four sections. 

usage 

declare ob j ect_ i nfo_$br ief entry (ptr, fixed bin(24), ptr, 
fixed bin(35); 

call object_info_$brief (segp, be, infop, code); 

1) segp is a pointer to the base of the object segment. 

(Input) 

2) be is the bit count of the object segment. (Input) 

3) infop is a pointer to the info structure in which the object 

information is returned. (Input) 

k) code is a standard Multics status code. (Output) 
Fntry : ob j ect_i nf o_$d i splay 

This entry returns, in addition to the $brief information, 
all the identifying data required by certain object display 
commands, such as pr i nt__l i nk_j nf o . 

Usage 

declare object_i nfo_$di splay entry (ptr, fixed bin(24), ptr, 
fixed bin(35); 

call object_i nfo_$di spl ay (segp, be, infop, code); 

1-4) as above. (Input/Output) 



Copyright, 
All rights 



1972, Massachusetts 
reserved . 



Institute of Technology 



obj ect__i nf o__ 



MULT I CS PROGRAMMERS' MANUAL 



Page 2 



Fntrv : ob ject_i nfo_$ 1 ong 



This entry returns/ in addition to the $brief and $display 
information/ the data required by the Multics binder. 



Usage 

declare obj ect_info_$ long entry (ptr, fixed b\n(2k), ptr, 
fixed bin(35); 

call obj ect_i nfo_$l ong (segp/ be, infop/ code); 
1-k) as above. (Input/Output) 

Information Structure 

The info structure is as follows: 



declare 1 info aligned/ 

2 version_number fixed bin, 

2 textp ptr, 

2 defp ptr, 

2 1 i nkp ptr/ 

2 symbp ptr, 

2 bmapp ptr, 

2 ting fixed bin, 

2 ding fixed bin, 

2 1 lng f i xed bi n, 

2 sing fixed bin, 

2 blng fixed bin, 

2 format/ 

3 old_format bit(l) unaligned/ 
3 bound bit(l) unaligned/ 
3 relocatable bit(l) unaligned/ 
3 procedure bit(l) unaligned/ 
3 standard bit(l) unaligned/ 
3 gate bit(l) unaligned/ 

2 cal l_del imi ter fixed bin, 

/*This is the limit of the $brief info structure.*/ 

2 compiler char(8) aligned/ 

2 compile_time fixed bin (71)/ 

2 userid char(32) aligned/ 

2 cvers al Igned, 

3 offset bit(18) unaligned/ 
3 length bit(18) unaligned/ 

2 comment/ 

3 offset bit(18) unaliged/ 
3 length bit(18) unaligned/ 
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2 source_map fixed bin, 

/♦This is the limit of the $display info structure.*/ 

2 rel_ text ptr, 

2 rel_def ptr, 

2 rel_link ptr, 

2 rel__symbol ptr, 

2 text_boundary fixed bin, 

2 stat i c_boundary fixed bin, 

2 def aul t__truncate fixed bin, 

2 opt ional_truncate fixed bin; 

/*This is the limit of the $long info structure.*/ 

1) vers ion_number 



2) textp 

3) defp 
k) linkp 

5) symbp 

6) bmapp 

7) ting 

8) ding 

9) ling 

10) sing 

11) blng 

12) old_format 



is the version number of the structure 
(currently = 1). 

is a pointer to the base of the text 
section. 



-of the 



-i-s — a- — po? nter — to — the — base 
definition section. 



is a pointer to the base of the linkage 
section. 

is a pointer to the base of the symbol 
section. 

is a pointer to the break map. 

is the length (in words) of the text 
section. 



is the length (in words) 
definition section. 



of 



the 



is the length (in words) of the linkage 
section. 

is the length (in words) of the symbol 
section. 

is the length (in words) of the break 
map . 

is "l"b if this segment is in the old 
format; otherwise it is "0"b. 
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13) bound 

Ik) relocatable 

15) procedure 

16) standard 

17) gate 

18) cal l_del imi ter 

Thi s is the limit of 

19) compi ler 

20) compi le_ t ime 

21) userid 

22) cvers. offset 



i s 



ii i it 



23) cvers. length 



2k) comment .of f set 



25) comment . length 



26) source_map 



l"b if this is a bound object 
segment; otherwise it is ,! 0"b. 

is u l"b if the object is relocatable; 
otherwise it is "Cb. 

is "l"b if it is a procedure; is M 0"b if 
it is nonexecutable data. 

is f, l M b if this is a standard object 
segment; otherwise it is "0"b. 

is "l"b if this is a procedure generated 
in the gate format; otherwise it is 
"0"b. 

is the call delimiter value if this is a 
gate procedure. 

the $brief info structure. 

is the name of the compiler which 
generated this object segment. 

is the date and time this object was 
generated. 

is the access id of the user in whose 
behalf this object was generated. 

is the offset (in words), relative to 
the base of the symbol section, of the 
aligned variable length character string 
which describes the compiler version 
used. 

is the length (in characters) of the 
compiler version string. 

is the offset (in words), relative to 
the base of the symbol section, of the 
aligned variable length character string 
containing some compiler generated 
comment . 

is the length (in characters) of the 
comment string. 

is the offset (relative to the base of 
the symbol section) of the source map. 
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This is the limit of the $display info structure. 
27) rel_text 



28) rel_def 

29) rel_link 

30) rel_symbol 

31) text_boundary 



32) stat i c__coundary 

33) def aul t_t runcate 



3^) opt ional__truncate 



is a pointer to the object's 
section relocation information. 



text 



is a pointer to the object's definition 
section relocation information. 

is a pointer to the object's linkage 
section relocation information. 



is a pointer to the object's 
section relocation information. 



symbol 



partially defines the beginning address 
of the text section. The text must 
begin on an integral multiple of some 
number, e.g., 0 mod 2, 0 mod 6^; this is 
that number. 



i s analogous to 
internal static. 



text_boundary for 



is the offset (in words), relative to 
the base of the symbol section, starting 
from which the symbol section may be 
truncated to remove nonessential 
information (e.g., relocation 

information) . 

is the offset (in words), relative to 

the base of the symbol section < starting 
from which the symbol section may be 
truncated to remove unwanted information 
(e.g., the compiler symbol tree). 



This is the limit of the $long info structure. 
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Name : parse_.fi le_ 



The parse__file_ module provides a facility for parsing an 
ASCII text into symbols and break characters. It is recommended 
for occasionally used text scanning applications. In 
applications where speed or frequent use are important, in-line 
PL/ I code to do parsing is recommended instead. 

A restriction of the procedure is that the text to be parsed 
be an aligned character string. 

The initialization entry points, par se_f i 1 e_J n i t__name and 
parse__f i 1 e_i n i t_ptr, both save a pointer to the text to be 
scanned and a character count in internal static storage. Thus, 
one text only can be parsed at one time. 



Entrv : parse__f i 1 e_$parse__f i 1 e_J ni t_name 



This entry initializes the module given a directory and an 
entry name. It gets a pointer to the desired segment and saves 
it for subsequent calls in internal static. 



Usage 



declare parse_f i 1 e_$ pa rse_.fi 1 e_i n i t_name entry (char(* ), 
char(*), ptr, fixed bin); 

call parse_f i 1 e_$ pa rse__.fi le_i n i t_name (dir, entry, p, 
code); 



1) dir is the directory name portion of the pathname of the 

segment to be parsed. (Input) 

2) entry is the entry name of the segment to be parsed. 

(Input) 

3) p is a pointer to the segment. (Output) 

k) code is an error code. It is zero if the segment is 

initiated. If nonzero, the segment cannot be 
initiated. It can return any code from hcs_$ i n i t i ate 
except er ror__tabl e_$segknown . 



Entrv : parse__f i 1 e_$par se_f i le_i ni t__ptr 



This entry initializes 
supplied pointer and character 
a pointer to the segment to be 



the parse__f i 1 e__ module with a 
count. It is used in cases where 
parsed is already available. 
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Usage, 

declare parse_f i 1 e_$parse__f i 1 e_i n i t_ptr entry (ptr, 
fixed bin); 

call parse_f i le_,$parse_f i le_Jni t_ptr (p, cc); 

Dp is a pointer to a segment or an aligned character 

string. (Input) 

2) cc is the character count of the ASCII text to be 

scanned. (Input) 

Entrv : parse_f i 1 e__$parse__f i 1 e_set_break 

Break characters may be defined by use of this entry. 
Normally/ all nonal phanumer i c characters are break characters 
(including blank and new line). 

Usage 

declare parse_f i le_$parse_f i 1 e_set__break entry (char (* ) ); 

call parse_f i le_$parse_f i le__set_break (cs); 

1) cs is a control string. Each character found in cs will 

be made a break character. (Input) 

Entrv : parse_.fi le_$parse_f i 1 e__unset_break 

This entry renders break characters as normal alphanumeric 
characters. 

Ms.ge 

declare parse_f i 1 e_$parse__f i 1 e_unset_J>reak entry (char(*)); 

call parse_f i le_$parse_f i le_unset_break (cs); 

1) cs is a control string each character of which will be 

made a nonbreaking character. (Input) 

Entrv : parse_.fi le_ 

The text file is scanned and the next break character or 
symbol is returned. Comments enclosed by /* and */ are skipped 
over. 
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declare parse__f i le__ entry (fixed bin, fixed bin, 
fixed bin(l), fixed bin(D); 

call parse_file_ (ci, cc, break, eof); 

1) ci is an index to the first character of the symbol or 

break character, (The first character of the text is 
considered to be character 1.) (Output) 

2) cc is the number of characters in the symbol. (Output) 

3) break is set to 1 if the returned item is a break 

character; otherwise it is 0. (Output) 

k) eof is set to 1 i f the end of text has been reached; 

otherwise it is 0. (Output) 

Entrv : parse_f i 1 e_$parse_f i 1 e_ptr 

This entry is identical to parse__file_ except that a pointer 
(with bit offset) to the break character or the symbol is 
returned instead of a character index. 

Usa.se 

declare parse__f i le_ $parse__f i le_ptr entry (ptr, fixed bin, 
fixed bind), fixed bin(D); 

call parse_f i 1 e__$parse_f i le_ptr (p, cc, break, eof); 

Dp is a pointer to the symbol or the break character. 

(Output) 

2-4) are the same as above. (Output) 

Entrv : parse_f i le_$parse_f i 1 e_cur_ 1 i ne 

The current line of text being scanned is returned to the 
caller. This entry is useful in printing diagnostic error 
messages. 



Usa.se 



declare parse_f i 1 e_$parse_f i le_cur_l i ne entry 
(fixed bin, fixed bin); 
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call par sc_f : 1 e_$par se_f i 1 e_cur_! i n.e (ci, cc); 

1-2) are the same as in parse_.fi le_ above. 

Entrv : parse_.fi 1 e_$parse_f i 1 e_l i ne_no 

The current line number of text being scanned is returned to 
the caller. This entry is useful in printing diagnostic error 
messages . 

Usage 

declare pa r se_f i 1 e_$ pa rse_.fi le_l i ne_no entry (fixed bin); 
call pa r se_f i le_$ pa rse_.fi le_l i ne_no (cl); 
1) cl is the number of the current line. (Output) 

Examples 

Suppose the file zilch in the directory dir contains the 
following text: 

name: foo; /*foo program*/ 

path_name: >bar; 

1 inkage; 

end; 

f i n i ; 

The following calls could be made to initialize the parsing 
of zi Ich: 

call pa r se_f s le_$ pa rse_.fi le_ini t_name (dir, zilch, 
p, code); 

call parse_f i le_$parse_ f i le_unset_break (">_ H ); 
declare atom char (cc) unaligned based (p); 
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Subsequent calls to pa r se_f M e_p t r would then yield the 
f ol lowi ng: 



atom 


break 


eof 


name 


0 


0 


• 
• 


l 


0 


foo 


0 


0 


• 


1 


0 


pathname 


0 


0 


• 
• 


1 


0 


>bar 


0 


0 


• 


1 


0 


1 i nkage 


0 


0 




1 


0 


end 


0 


0 


• 


1 


0 


f i nl 


0 


0 


• 

/ 


1 


0 






1 



(END) 
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Name ; plot_ 

The procedure plot_ is a user interface to the Multics 
Graphics System. It creates a two dimensional graph from input 
data for use with Multics display terminals. The graph created 
is a Cartesian graph, scaled so as to permit maximum coverage of 
the screen, and labeled in convenient increments to facilitate 
reading. This routine can be made to plot either with vectors 
connecting the data points, with a specified character displayed 
at each point plotted, or both. It also has facilities that 
enable the user to append a new plot over the one being currently 
displayed (in which case the new plot is scaled to match the old 
one), to suppress the grid (in which case only the left-most and 
lowest lines are displayed, with tic marks at increments), and to 
direct that the graph be scaled equally in both directions. 

For a more extensive description of graphics facilities, see 
the MPM Reference Guide section Graphics Support on Multics. 

Usase, 

declare plot_ entry ((*)float bin, (*)float bin, fixed bin, 
fixed bin, char(D); 

call plot_ (x, y, xydim, vec_sw, symbol); 

1) x is an array of x coordinates of points to be plotted. 

(Input) 

2) y is an array of y coordinates of points to be plotted. 

( I nput) 

3) xydim is the number of elements in the x and y array pairs. 

( Input) 

k) vec_sw ■ 1 if the vectors but no symbol are desired; 
= 2 if the symbol and vectors are desired; 
= 3 if the symbol but no vectors are desired. (Input) 

5) symbol is the symbol to be plotted at each point. (Input) 
Notes 

It is possible, by repetitive calls to plot_, to display any 
set of graphs on top of one another. All graphs after the first 
graph will be scaled to the scale of the first. A call to plot_ 
will erase the screen only if there was a call to either 
plot__$init or plot__$initf prior to it. The only exception is 
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that the first call to plot__ in a process will always erase the 
screen whether or not plot__$init or plot_$initf have been called. 
Default values for options are dotted grid, automatic scaling / no 
labels/ and 1 i near- I i near plot. 

Entry : plot_$init 

This entry allows the user to set parameters controlling the 
type of plotting performed. The parameters specify the type of 
graph desired (log-log/ linear/ etc.), the type of grid desired 
(If any)/ and whether or not plot__ is to scale both axes equally. 
A call to this entry also ensures that the next call to plot., 
will erase the screen. 



declare plot_$init entry (char(*)/ char(*)/ fixed bin/ 

float bin, fixed bin, fixed bin); 

call plot_$init (xlabel/ ylabel/ type, base, grid_sw/ 
eq__scal e_sw) ; 



1) xlabel 

2) ylabel 

3) type 



4) base 

5 ) gr i d_sw 



is the label desired along the x axis. (Input) 

is the label desired down the y axis. (Input) 

= 1 for 1 i near- 1 i near plot; 
= 2 for log-linear plot (log on x axis); 
= 3 for linear-log plot (log on y axis); 
= k for log-log plot. (Input) 

is the logarithm base (for logarithmic plots). 
( I nput ) 



= 0 

= 1 

= 2 

= 3 



f tic marks and values are desired; 

f dotted grid and values are desired; 

f solid grid and values are desired; 

f no grid or values are desired. (Input) 



6) eq_scale - ..sw = 0 if normal scaling is desired; 

= 1 if the plot is to be scaled equally in both 
directions. (Input) 

Entry: plot_$initf 

This entry is similar to plot_$init but is callable from 
FORTRAN * 
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Usage 



integer xlabel (<n>), ylabel (<n>), xlng, ylng, type, 
grid__sw, eq__scale_sw 

real base 

equate initf, plot_$initf 

call initf (xlabel, xlng, ylabel, yl ng, type, base, 
gr i d_sw, eq_scal e__sw) ; 



1) xlabel 

2) xlng 

3) ylabel 
k) ylng 

5) type 

6) base 

7) gr i d_sw 



is the label desired along the x axis. (Input) 

is the length (in characters) of xlabel. (Input) 

is the label desired down the y axis, (Input) 

is the length (in characters) of ylabel. (Input) 

= 1 for linear-linear plot; 

= 2 for log-linear plot (log on x axis); 

- 3 for linear-log plot (log on y axis); 
= k for log-log plot. (Input) 

is the logarithm base (for logarithmic plots). 
(Input) 

= 0 if tic marks and values are desired; 
= 1 i f dotted grid and values are desired; 
■ 2 if solid grid and values are desired; 

- 3 if no grid or values are desired. (Input) 



S) eq__scale_sw ■ 0 i f normal scaling is desired; 

■ 1 if the plot is to be scaled equally in both 
directions. (Input) 

Entrv : pi ot_$ scale 

This entry allows a user to set his own scaling by allowing 
him to specify the extent of the axes in the x and y directions, 
if this scaling feature is desired, this entry must be called 
before any call to plot_ (i.e., immediately after a call to 
plot__$init or plot_$ i n i tf ); otherwise, it is ignored. 
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declare plot_ $scale entry (float bin, float bin, 
float bin, float bin); 

call plot_$scale (xmin, xmax, ymin, ymax); 



1 ) xm i n 


i s 


the 


des i red 


low bound of 


the x axis. 


( Input) 


2 ) xmax 


i s 


the 


des i red 


high bound of 


the x axis. 


(Input) 


3) ymin 


i s 


the 


des i red 


low bound of 


the y axis. 


( Input) 


k) ymax 


i s 


the 


desi red 


high bound of 


the y axis. 


( Input) 


Example 















p__sin: proc; 



declare x(180) float bin, 
y(180) float bin, 
i fixed bin, 

pi float bin static internal initial (3.14159e0), 
three_cyc float bin, 

plot_ entry ((*)float bin, (*)float bin, fixed bin, 

fixed bin, char(D), 
plot_$init entry (char(*), char(*), fixed bin, 

float bin, fixed bin, fixed bin), 
(sin, float) builtin; 

three_cyc = beO*pi /180e0; 

do i = 1 to 180; 

x(i) = three_cyc * float (i-1); 

y( i ) = sin (x( i )); 

end; 

call plot__$init ("this is a sine curve", "automatically 
scaled", l,0e0, 1,0); 

call plot, (x, y, 180, 1, ""); 

return; 
end; 



(c) Copyright, 1972, Massachusetts Institute of Technology 
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•this is a sine curve 
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Name : random_ 

The procedure random_ is a random number generator with 
entry points which, given an input seed, generate a pseudo-random 
variable with a uniform, exponential, or normal distribution. 
The seed is an optional input argument; if it is not included in 
the call, an internal static variable is used and updated. 

For one set of entry points, each call to random,, produces a 
single random number. To obtain a sequence of random numbers 
with the desired distribution, repeated calls are made, each time 
using the value of the seed, returned from a call, as the input 
value of the seed for the next call in the sequence. 

There is an additional set of entry points which return an 
array with a sequence of random numbers. The first element of 
the array is generated from the input seed and the last element 
corresponds to the returned value of the seed. In addition, for 
the uniform and normal distributions, there are entry points 
which produce the antithetic random variables, either singly or 
as a sequence. For any given seed, the random variable produced 
is negatively correlated with that produced at the corresponding 
entry. 

Entrv : random_$un i form 

The entry point random_$un i f orm generates a random number 
0.0 < random_no < 1.0. The sequence of random numbers has a 
uniform distribution on the interval zero to one. 

Usage 

declare random_$un i form entry (float bin(27)); 
call random_$un i f orm ( random__no ) ; 

or 

declare random_$un i f orm entry (fixed bin(35), float 
bin(27)); 

call random_$un i form (seed, random__no); 

1) seed is the optional (see Notes ) seed that is used 

to generate the random number. The value of 
seed is modified by this entry. The value 
returned is the seed that is used to generate 
the next random number of the sequence. The 
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2) random_no 



value of seed must be a nonzero positive 
integer. (Input/Output) 

is the random number that is generated. 
(Output) 



Entrv : random_$uni f orm_ seq 

This entry point returns an array of random numbers from the 
uniform sequence. 



Usage 



declare random_$un i form_seq entry (float bin(27), 
f i xed bin); 

call random_$un i f orm_seq (array / ar ray_s i ze ); 



or 



declare random_$un i f orm_seq entry (fixed bin(35), 
float bin(27), fixed bin); 



call random_$un i form_seq (seed, array, array_size); 



1) seed 



2) array (a) 



3) array_size 



is the optional (see Notes ) seed used to 
generate array. See References (2). The 
value returned corresponds to the random 
number returned as array (array_s i ze ) . 
( Input/Output) 

is an array of the generated random numbers 
where & is greater than or equal to 
array__size. (Output) 

specifies the number of random variables to 
be returned in array. (Input) 



Entrv : random_$un i form_ant 

This entry point generates a uniformly distributed random 
number, random__ant, that is negatively correlated with random_no 
produced by the entry random_$un i form. For any particular value 
of the seed, ( random_ant + random_no) = 1.0. 



Usage 



declare random_$un i form__ant entry (float bin(27)); 
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call random_$un i form_ant ( random_ant ) ; 

or 

declare random_ $un i f orm__ant entry (fixed bin(35), float 
bin(27)); 

call random_$un i form_ant (seed / random_ant); 

1) seed is the optional (see Notes ) seed used to 

generate the random number. (Input/Output) 

2) random_ant is the random number that is generated. 

(Output) 

Entry : random_$un i form_ant_seq 

The entry point random_$un i f orm ant_seq returns an array/ 
ant_array, of uniformly distributed random numbers that are 
negatively correlated with the array produced by 
random_$un i form_.seq. For any particular value of the seed, 
(ant_array (jj + array(j_)> = 1.0, for 1 between one and 
array_s i ze . 

Usage 

declare random__$un i f orm_ant__seq entry (float bin(27), 
f i xed bin); 

call random_$un i form_ant_seq (ant_array, array_size); 

or 

declare random_$un i f orm_ant_seq entry (fixed bin(35), float 
bin(27), fixed bin); 

call random_$un i form_ant_seq (seed, ant_array, array_size); 

1) seed is the optional seed used. (Input/Output) 

2) ant_array (a) is the array of generated random numbers 

where a is greater than or equal to 
array_size. (Output) 

3) array__size is the number of values returned in 

ant_array. (Input) 
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Entry : random__$normal 

The entry point random_$normal generates a random number/ 
-6.0 < random_jio < 6.0. The sequence of random numbers has an 
approximately normal distribution with a mean of zero and a 
variance of one. The random number is formed by taking the sum 
of twelve successive random numbers from the uniformly 
distributed sequence and then adjusting the sum for a mean of 
zero. 

Usage 

declare random_$normal entry (float bin(27)); 
call random_$normal (random_no); 

or 

declare random_$normal entry (fixed bin(35)/ float 
bin(27)); 

call random_$normal (seed/ random_no); 

Same arguments as above. 

Entrv : random_$normal_seq 

The entry point random_$norma l__seq generates a sequence/ of 
length array_size/ of random variables with an approximately 
normal distribution. 

Usage 

declare random_$normal_seq entry (float bin(27), 
fixed bin); 

call random_$normal_seq (array/ array_size); 

or 

declare random_$normal — seq entry (fixed bin(35), float 
bin(27)/ fixed bin); 

call random_$normal_seq (seed/ array/ array_size); 
Same arguments as above. 
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Entry : random_$normal_ant 

The entry point random_$norma l_ant generates a random 
number/ random_ant, that is negatively correlated with random_no 
produced by the entry random_$norma 1 . For any particular value 
of the seed/ (random__ant + random__no) = 0.0. 

declare random_$normal_ an t entry (float bin(27)); 
call random_$normal_ant ( random__ant ); 

or 

declare random_$normal_ant entry (fixed bin(35), float 
bin(27)); 

call random_$normal__ant (seed/ random_ant); 

Same arguments as above, 

Entrv : random_$normal_ant_seq 

The entry point random_ $normal_ant_seq generates a sequence/ 
of length array_size/ of random variables with approximately 
normal distribution. These variables are negatively correlated 
with those produced by the entry point random_$normal_seq . 

Usage 

declare random_$normal_ant_seq entry (float bin(27)/ 
fixed bin); 

call random__$normal_ant_seq (ant_array/ array_size); 

or 

declare random_$normal_ant_seq entry (fixed bin(35), 
float bin(27)/ fixed bin); 

call random_$normal_ant_seq (seed/ ant_array/ array_size); 

Same arguments as above. 

Entry : random_$exponent i al 

The entry point random_$exponent i a 1 generates a positive 
random number. The sequence of random numbers has an exponential 
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distribution with a mean of one. The random number is generated 
by taking successive random numbers from the uniformly 
distributed sequence and applying the VonNeumann method (see 
References (2)) for generating an exponential distributed random 
var i able. 

Usage 

declare random_$exponent i al entry (float bin(27)); 
call random_$exponent i al (random_no); 

or 

declare random_$exponent i al entry (fixed bin(35), float 
bin(27)); 

call random_$exponent ial (seed/ random_no); 

Same arguments as above. 

Entry : random__$exponent i al_seq 

The entry point random_$exponent i al_seq produces an array of 
exponentially distributed random variables. 

Usage 

declare random_$exponent i al__seq entry (float bin(27), 
fixed bin); 

call random_$exponent ial_seq (array/ array_size); 

or 

declare random_$exponent i al = seq entry (fixed bin(35)/ float 
bin(27)/ fixed bin); 

call random_$exponent ial_seq (seed/ array, array_ size); 

Same arguments as above. 

Entrv : random_$get_seed 

The entry point random_ $get_seed is used to obtain the 
current value of the internal seed (see Notes ) . 
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Usage 

declare random_$get_seed entry (fixed bin(35)); 

call random_$get_seed ( seed_va 1 ue ) ; 

1) seed_value is the current value of the internal seed. 

(Output) 

Entry : random_$set_seed 

The entry point random_$set_ seed is used to set the value of 
the internal seed. This internal seed is used as the seed for 
the next call to any random_ entry point in which the optional 
argument seed is not provided (see Notes ) . 



Usage 



declare random_$set_seed entry (fixed bin(35)); 
call random_$set__seed ( seed_val ue ) ; 

1) seed_value is the value to which the internal seed is 

set. seed_ value must be a nonzero positive 
integer. (Input) 



Notes 



All non-optional arguments must be included in the call/ 
even if only the value of some are of interest. For all entry 
points (except random_$se t_seed and random_$get_seed ) , if the 
optional parameter seed is not provided in the call/ an internal 
seed is used and updated in exactly the same manner as a seed 
provided by the caller. This internal seed is maintained as an 
internal static variable. At the beginning of a user's process/ 
it has a default value or 4084114320. Its value is changed only 
by calls to random__$set_seed or by calls to other entry points in 
which the optional parameter seed is not included. 

If the value of a seed is zero, the new value of the seed 
and the random numbers will be zero. If the value of a seed is 
negative/ the low order 35 bits of the internal representation 
will be used as the seed; if nonzero, a valid value will be 
returned for the seed and the random numbers. A given seed will 
always produce the same random number from any given entry point. 
Since all entry points use the same basic method for computing 
the next seed, the distribution of the sequence produced by calls 
to any given entry point will be maintained/ although the input 
seed used may have been produced by a call to a different entry 
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point. In other words, the user need keep only a single value of 
the next seed even though he calls more than one of the entry 
points. However, in general, the different entry points will, 
for any given input seed, produce different values for the next 
seed. 

On the other hand, the user may generate independent streams 
of random numbers by beginning each stream with separate initial 
seeds and maintaining separate values for the next seed. 

The uniformly distributed random number sequence is 

generated using the Tausworth method (see References (1) and 

(3)). The algorithm, in terms of abstract registers A and B, is 
described below. 

The parameter n is one less than the number of used bits per 
word (for Multics, use n = 35). The parameter m is the amount 
of shift (for Multics, m = 2). 

a) Let register A initially contain the previous random 
number in bit positions 1 to n with zero in the sign bit 
(position 0). 

b) Copy register A into register B and then right-shift 
register B m places. 

c) Exclusive-or register A into register B and also store 
the result back into register A. (Registers A and B now 
have bits for the new random number in positions m + 1 to 
n, but still contain bits from the old n bit random 
number in position 1 through m. ) 

d) Left-shift register B (n-m) positions. (This places m 
bits for the new random number in positions 1 to m of 
register B and zero bits in positions m + a through n.) 

e) Exclusive-or register B into register A and zero out 
register A's sign bit. (Register A now contains all n 
bits of the new random number.) 

f) To obtain a random number between 0.0 and 1.0, we divide 
the n bit integer in register A by 2**n. The contents of 
register A must be saved for use in generating the next 
random number. 

In random_, a word is considered as being 36 bits long 
including the sign bit. This gives rise to a 35 bit integer 
random number. Since in Multics, a floating point number has a 
27 bit mantissa, this means different seeds may produce the same 
floating point value; however, the interval between identical 
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values of the integer seed is equal to the cycle length of the 
integer random number generator. In random_, a shift of 2 is 
used, which gives a cycle of (2**35)-l (see References (1)). The 
essence of the assembly language code used by random., is given 
below. 



equ 


shift, 2 


use a shift of 2 


ldq 


seed 


seed into the Q register 


qrl 


shift 


shift the seed right 


ersq 


seed 


exclusive-or to the seed 


ldq 


seed 


put result in the Q register 


ql s 


35-shift 


shift left 


erq 


seed 


exclusive-or the previous result 


anq 


=o377777777777 


save only 35 bits 


stq 


seed 


return the value of the seed 


Ida 


seed 


load the integer value 


lde 


Qb25, du 


convert to floating point 


fad 


=0., du 


normalize the floating point 


fst 


random_no 


return a random number 



References 

1) Golomb, S. W., Welch, L. R. , Goldstein, R. M. , and Hales, 
A. W., $hift Register Sequences, Holden-Day, 1967, p. 97. 

2) Taub, A. H., John VonNeumman. Col lected WorKs, V, 
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3) Whittleself, John R. B., "A Comparison of the Correlation 
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Name : read_Jist_ 

This procedure is used to read and convert free-formatted 
input data. It reads a series of input values from the I/O 
stream "user^jnput" and interprets each in terms of the data type 
of the corresponding variable in the calling sequence. (See 
Notes below for acceptable data types and break characters.) If 
an input value is discovered to have incorrect syntax, a comment 
is printed asking that the input value (and any following it) be 
retyped. 

If the line read contains fewer values than were requested 
in the calling sequence, by default read_Jist__ types out a 
message of the form: 

n more input values expected 

and attempts to read another line from the stream "user^input". 
This does not occur before the first input line. 

Since this procedure can be called with a varying number of 
arguments, it is not permissible to include a parameter attribute 
list in the declaration of the various entry points. 

Usage 

declare read_Jist_ entry options (variable); 

call read__l i st_ (vJL vl, . . • , va); 

1) vi is any variable of the calling program and can be 

any scalar quantity. (Output) 

Entrv : read_l i st_$no_ prompt 

This entry works exactly as read__list_ does except that 
there is no prompting if the line read contains fewer values than 
were requested in the calling sequence. Instead, read_Jist_ 
merely attempts to read another line until all requested values 
have been suppl ied. 

Usage 

declare read_l i st_$no__prompt entry options (variable); 
call read_l i st_$no_prompt (vJL, v2, vn); 
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I) vj. is as above. (Output) 

Entry ; read_l i st__$prompt 

This entry works as read__list_ does except that alternate 
arguments are taken to be prompting messages to be typed on the 
stream "user_ output". No other prompting is done. 

Usage 

declare read_l i st_$ prompt entry options (variable); 
call read_l i st_$prompt (pJL vl, p£, vl/ p&, va); 

1) pi is a character string to be typed on the user's 

terminal. It is typed out via ioa_$nnl / so there 
is no new line after a message unless the last two 
characters of the string are ""7". (See the MPM 
subroutine write-up for ioa_. ) If any prompting 
argument is a null character string/ that 
prompting message is not typed. If the number of 
arguments is odd, the last (unmatched) prompting 
argument is taken as a message to be typed after 
reading the last variable. If the user 
anticipates input by typing several input values 
on one line/ intermediate prompting messages are 
omitted. (Input) 

2) vi is as above. (Output) 

Entrv : read_l i st__$scan_s t r i ng 

This entry works as read_ list_ does except that instead of 
reading input from the user's terminal it considers its first 
argument to be a character string to be scanned and converted as 
though it had been read from "user_i nput" . Subsequent argument 
values are supplied from the contents of the first argument. 

Usage, 

declare read_J i st_$scan_str ing entry options (variable); 

call read_J i st_$scan_ str ing (scan_str ing/ nret/ 
vl/ vl/ va>; 

1) scan_string is a character string (char(*)) to be scanned as 
though it had been read from ,f user_input n . 
(Input) 
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2) nret is a fixed bln(17) number containing/ upon return/ 

the number of arguments actually supplied in 
scan__ string. The reason for nret is that there is 
no prompting and no way to ask for more values if 
there weren't enough to begin with. A value of 
nret less than 0 indicates a syntax error/ with 
the absolute value of nret indicating which 
argument was bad. (The arguments following that 
one are not processed.) Counting for nret starts 
with vl as argument one. (Output) 

Notes 



Input conversion is currently implemented for the following 
Multics PL/I data types using the rules for the formation of PL/ I 
constants: 

single precision fixed point 

double precision fixed point 

single precision floating point 

double precision floating point 

nonvarying character string 

varying character string 



nonvarying bit string 
varying bit string 
poi nter 

Character strings can be typed without enclosing quotation 
marks if they don't contain any of the delimiters listed below. 



A fixed point number can be typed in octal format if it is 
followed by the letter "o". 

Floating point constants can be typed without an explicit 
exponent or decimal point. 

Input pointer values are typed as follows: 
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dl|d2 



means a pointer to 
d2, bit offset 0. 



segment number dl / word 



offset 



dl|d2(d3) 



means a pointer to 
d2, bit offset d3. 



segment number dl/ word 



offset 



where dl and d2 are octal integers and d3 is a decimal integer. 

Fixed point constants can be typed in binary form; e.g., 
1011b. 

Typed character or bit strings which are too large or too 
small for the space declared in the calling program are truncated 
or padded/ respectively/ according to the usual PL/ I language 
rules. 

The delimiters allowed in the input line are space (0)/ tab 
(HT)/ comma (/)/ and the new-line character (NL). Successive 
input values can be separated by any number of blanks and/or 
tabs. Other combinations of delimiters have the following 
mean i ngs : 

/NL = NL 



no new input value for corresponding 
argument 



NL/ 



NL|*/ 



NLHT/ 



mi 



NL 
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Name : revers ion_ 

This procedure causes the handler currently established for 
the given condition in the calling block activation to be 
disestablished. If no handler for the given condition is 
established in the calling block activation/ no action is taken. 
A description of the condition mechanism is given in the MPM 
Reference Guide section on The Multics Condition Mechanism. 

Usage 

declare reversion_ entry (char(*)); 

call revers ion__ (name); 

1) name is the name of the condition for which the handler is 
to be disestablished. (Input) 

Notes 

The condition names unci a imed_s i gnal and cleanup are 
obsolete special condition names and should not be used. 

A call to reversion_ must be used only to revert a handler 
established by a call to condition^, (see the MPM subroutine). 
reversion_ must not be used to revert a handler established by a 
PL/ I on statement. 

In PL/I Version 2, when a call to reversion^ appears within 
the scope of a begin block or internal procedure of a procedure, 
the no_qui ck_bl ocks option must be specified in the procedure 
statement of that procedure. The no_qu i ck_b locks option is a 
nonstandard feature of the Multics PL/ I language and, therefore, 
programs using it may not be transferable to other systems. 



(c) Copyright, 1972, Massachusetts 
All rights reserved. 
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Name : signal_ 

This procedure signals the occurrence of a given condition. 
A description of the condition mechanism and the way in which a 
handler is invoked by signal^ is given in the MPM Reference Guide 
section, The Multics Condition Mechanism. 

Usage 

declare signal_ entry (char(*), ptr, ptr); 
call signal_ (name, mcptr, info_ptr); 

1) name is the name of the condition to be signalled. 

(Input) 

2) mcptr points to the machine conditions at the time the 

condition was raised. This argument is for use by 
system programs only in order to signal hardware 
faults. In user programs, this argument should be 
null if a third argument is supplied. This 
argument is optional. (Input) 

3) info_ptr points to information relating to the condition 

being raised. The structure of the information is 
dependent upon the condition being signalled; 
however, conditions raised with the same name 
should provide the information in the same 
structure. Important: all structures must begin 
with a standard header. The structures provided 
with system conditions are described in the MPM 
Reference Guide section, System Conditions and 
Default On Unit Actions. The format for the 
header is described in the MPM Reference Guide 
section, The Multics Condition Mechanism. This 
argument is intended for use in signalling 
conditions other than hardware faults. This 
argument is also optional. (Input) 

Notes 

If signal_ returns to its caller, indicating that the 
handler has returned to it, the calling procedure should retry 

the operation that caused the condition to be signalled. 

The PL/ I signal statement differs .from the signal_ 
subroutine in that the above parameters cannot be provided in the 
signal statement. 
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Name : stu. 



The stu_ (Symbol Table Utility) procedure provides a number 
of entry points for retrieving information from the segment 
symbol table section of an object segment. Multics compilers 
will produce a segment symbol table only when explicitly 
instructed to do so (e.g., with the use of the PL/I table 
option) . 

Entry : s tu_$f i nd_header 

This entry, given an ascii name and a pointer to any 
location in a (possibly bound) object segment, searches the given 
segment for the symbol table header corresponding to the given 
name . 

Usage 

declare s tu_$f i nd_header entry (ptr, char(32) aligned, 
fixed bin(22)) returns (ptr); 

header_pt = stu_$f i nd__header (seg_pt, name, be); 



1) 
2) 



seg_pt 



name 



3) be 



k) header__pt 



points at 
(Input) 



any location in the object segment. 



is the ascii name of the program whose symbol 
header is to be found (same as the name of 

the segment if the object segment is not 

bound). (Input) 

is the bit count of the object segment; if 
zero, find header will determine the bit 
count itself. (Input) 

will point to the header if it could be found 
or will be null if the header could not be 
found. (Output) 



i stu_ i MULTICS PROGRAMMERS 1 MANUAL 



Page 2 



Notes 



Since determining the bit count of a segment is relatively 
expensive, the user should provide the bit count if he has it 
available (i.e., as a result of a call to hcs_$ i n i t i a te_count ) . 

If seg_pt is not null, decode_obj ect is called; the symbol 
header is assumed to start at word 0 of the symbol segment. If 
seg_pt is null, hcs_$make_ptr is used to locate the 
"symbol_table" segdef in the segment with the given name. 



Entry : stu_$f i nd_block 



This entry point, given a pointer to the symbol table header 
of a procedure, searches for a procedure symbol block 
corresponding to a given block in the object program. 

Usage 

declare s tu_$f i nd_b lock entry (ptr, char(*) aligned) 
returns (ptr); 

block__pt = s tu__$f i nd__b lock (header__pt, name); 

1) header_pt points at a symbol table header. (Input) 



2) name is the ascii name of the symbol block to be 

found. The name of a symbol block is the 

same as the first name written on a procedure 
statement. (Input) 

3) block_pt will point to the symbol block if found or 

will be null if the block could not be found. 
(Output) 



Entrv : s tu_$get_b 1 ock 



This entry point, given a pointer to the stack frame 
corresponding to an active PL/1 procedure or begin block, returns 
pointers to the symbol table header and symbol block associated 
with the procedure or begin block. Null pointers will be 
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returned if the stack frame does not belong to a PL/1 program or 
if the PL/1 program does not have a symbol table. 

Usage 

declare stu_$get_b lock entry (ptr, ptr, ptr); 

call stu_$get__block (stack_pt, header_pt / block__pt); 

1) stack_pt points at an active stack frame. (Input) 

2) header_pt will be set to point at the symbol table 

header. (Output) 

3) block_pt will be set to point at the symbol block. 

(Output) 

Entrv : stu_$f i nd__symbol 

This entry point, given a pointer to the symbol block 
corresponding to a procedure or begin block, searches for the 
symbol node associated with a specified variable name. If the 
name is not found in the given block, the parent block is 
searched, This is repeated until the name is found or the root 
block of the symbol structure is reached, in which case a null 
pointer is returned. 

Usage 

declare stu_$f i nd_symbol entry (ptr, char(*) aligned, fixed 
bin) returns (ptr); 

symbol__pt = s tu_$f i nd__symbol (block__pt, name, steps); 

1) block_pt points at the symbol block where the search 

is to begin. (Input) 
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2) 



name 



3) 



steps 



k) symbol_.pt 



is the ascii name of the symbol to be found, 
name may be a completely qualified structure 
name (i.e., "a.b.c"), in which case the 
symbol node for the lowest level item will be 
found. (Input) 

will be set to the number of steps along the 
parent chain that were taken before the 
symbol was found. steps will be 0 if the 
symbol was found in the given block. 
(Output) 

will point to the symbol node if found or 
will be null if the symbol could not be found 
in any block. (Output) 



Entry : stu_$decode_value 



This entry point is called to decode values stored 
symbol node (see Reference Data Section of this manual). 



• n 



Usage 



declare stu_$decode_val ue entry (fixed bin(35), 
fixed bin) returns (fixed bin(35)); 



ptr, ptr, 



value = s tu_$decode_va 1 ue (v, stack_pt, ref_.pt, code); 



1) 
2) 



stack_pt 



is the value from the symbol node to be 
decoded. (Input) 

is a pointer to the active stack frame for 
the procedure or begin block corresponding 
to the symbol block in which the symbol node 
whose value to be decoded appears. (Input) 



3) ref_pt 



is the value of the reference pointer if the 
variable corresponding to the symbol node is 
based. (Input) 
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k) code 



5) value 



will be set to 0 ff the value was 
successfully decoded and to J \f t h e valu* 
•could not be decoded. (Output) 



will be the 
(Output) 



decoded value if code = 0. 



Entry : stu__$get__ref erence 

po i n t , 



This entry 
corresponding to 



given a pointer to t^e 
a PL/1 based variable, attempts to 
value of the pointer variable that appeared in 

the value of "p" in "del a based 

the declaration does not have 
t h e pointer could not bp 



deel arat ion ( ? . e 

null pointer will he returned 
the proper form or if the value 
de termi ned . 



iipti 

o* 



symbol node 
return the 
the based 
(p); u ). A 



Usage 



1) 
2) 



dec"\ar^ s tu_$p-et_ref erence entry (ptr, otr) returns (ptr); 
ref_pt - s tu_$o-et_ref erence (sym^ol_ot, staok_pt); 
symbol pt 



stack pt 



points at the symbol node for t K e Hasp^ 
variable. (Input) 

points at the active stack fram^ for t^e 
procedure or begin block cor resoond i ne to 
the symbol block in wMch the symhol noHe is 
found. (Input) 



3) ref_pt 



will be set to the valup of the pointer 
variable or will be null i f the value couH 
not be determined. (Output) 
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Notes 



A null pointer will be returned for any one of a number of 
reasons. Some of these are: 

1) the based variable was declared as 



2) the pointer base does have an active stack frame, 
Entrv : stu__$get_address 

This entry point / given a pointer to a symbol node, an 
active stack frame and a vector of subscripts, determines the 
address of the specified variable. 



declare stu_$get_address entry (ptr, ptr, ptr, ptr) returns 



add_.pt - stu_$get_address (symbol_pt, stack_pt, ref__pt, 
subs_pt ) ; 



del a based; 



Usage 



(ptr); 



1) 



symbol_pt 



points at the symbol table node. (Input) 



2) 



s tack_pt 



points at the active stack frame for the PL/1 
procedure or begin block corresponding to 

the symbol block in which the symbol node is 
found. (Input) 



3) 



ref_pt 



is the value of the reference pointer to be 

used if the symbol node corresponds to a 
based variable. If ref_pt is null, 
get__ address will call get_ref erence to 
determine the value of the pointer appearing 
in the original declaration. (Input) 
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h) subs_.pt 



points at a vector of single precision fixed 
point subscripts. The number of subscripts 
is assumed to match the number required by 
the declaration. This argument may be null 
if the symbol node does not correspond to an 
array. (Input) 



5) add_.pt 



will point to the full bit address of the 

variable corresponding to the symbol node or 

will be null if the address could not be 
determined. (Output) 



Notes 



Poi nters 
obtained from 



to the text or linkage segment, 
the specified stack frame. 



if required, are 



Entrv : s tu_$get_addr 



This entry point, given a pointer to a symbol node, a vector 
of information pointer and a pointer to a vector of subscripts, 
determines the address of the specified variable. 



Usage 



declare s tu_$get_addr entry (ptr, (3)ptr, ptr, ptr) returns 
(Ptr); 

add_.pt = stu_$get_addr (symbol_pt, info, ref_pt, sub_.pt ); 

1) symbol_.pt points at the symbol table node. (Input) 

2) info is an array of pointers, info(l) points at 

the active stack frame; info(2) points at the 
linkage section; info(3) points at the text 
segment. (Input) 
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3) ref_.pt is the value of the reference pointer to be 

used if the symbol node corresponds to a 
based variable. If ref_pt is * null, 
get_address will call get_ ref erence to 
determine the value of the pointer appearing 
in the original declaration, (Input) 

k) subs__pt points at a vector of single precision fixed 

point subscripts. The number of subscripts 
is assumed to match the number required by 
the declaration. This argument may be null 
if the symbol node does not correspond to an 
array. (Input) 

5) add_.pt will point to the full bit address of the 

variable corresponding to the symbol node or 
will be null if the address could not be 
determined. (Output) 

Entrv : s tu_$get_l i ne_no 

This entry/ given a pointer to a symbol table block and an 

offset in the text segment corresponding to the block, determines 
the line number, starting location, and number of instructions in 
the source statement containing the specified instruction. 

Usage 

declare sfu _Jget line no entry (ptr, fixed binU8) 4 fixed 
binTiS), fixea' bin(18)) returns (fixed bin(18)); 

line_no = s tu_$get_1 i ne__no (block__pt, offset, start, num); 

1) block_.pt points at the block node. (Input) 

2) offset is the offset of an instruction in the text 

segment. (Input) 

3) start will be the offset in the text segment of the 

first instruction generated for the source 
line containing the specified instruction, or 
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will be -1 If the line could not be found. 
(Output) 

k) num will be the number of instructions generated 

by the specified source line. (Output) 

5) line_no will be the line number of the source 

statement which generated the given 
instruction. (Output) 



Notes 



1) If the source program contains include files, all line 
numbers refer to the expanded source segment. 

2) No distinction is made between several statements occurring 
on the same source line, "start" will be the starting location 
of the code generated for the first statement on the line and 

"num" will be the total length of all the statements on the 
1 i ne. 



Entrv : stu_$get_l ocat ion 

This entry / given a pointer to a symbol table block and the 
line number of a source statement in the block / returns the 
location in the text segment of the first instruction generated 
by the specified source line. 

Usage 



declare stu_$get_l ocat ion entry (ptr, fixed bin(18)) 
returns (fixed bin(18)); 



offset ■ stu__$get_l ocat ion (block_pt, line__no); 



1) b lockup t 



points at the block node. (Input) 



I I 
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2) line_no specifies the source line number. (Input) 

3) offset will be the offset in the text segment of the 

first instruction generated by the given 
line, or will be -1 if no instructions were 
generated by the given line. (Output) 

Example 

We will illustrate the use of some of the procedures 
documented above by presenting a sample procedure which is called 
wi th 

stack__pt a pointer to the stack frame of PL/ 1 procedure 

symbol an ascii string giving the name of a user symbol 
in the PL/ I program 

and subs_.pt a pointer to an array of integers giving subscript 
val ues . 

The procedure will determine the address, data type, and size of 
the specified symbol. If any errors occur, the returned address 
will be nul 1 . 

example: proc (stack_pt, symbol, subs__pt, size) returns (ptr); 

declare stack pt pt< 

symbol aligned char(*), 

subs__pt Ptr, 

size fixed bin(35); 

declare (header_pt, block_pt, symbol_pt, ref__pt, sp, 
add_pt) ptr, 

(i, steps, code) fixed bin, 
stu_$get_block entry (ptr, ptr, ptr), 



I I 
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stu_$f i nd_symbol entry (ptr, char(*) aligned, 
fixed bin) returns (ptr), 

stu_$get__address entry (ptr, ptr, ptr, ptr) 
returns (ptr), 

stu_$decode_va1ue entry (fixed bin(35), ptr, 
ptr, fixed bin) returns (fixed bin(35)); 

declare 1 frame based, 
2 sklp(32) fixed, 
2 display ptr; 

% include symbol_node; 

/* determine header and block pointers */ 

call stu_$get_block (stack_ pt, header_pt, 
block_pt) ; 

if block_pt ■ null then return (null); 

/* search for specified symbol */ 

symbol_.pt ■ stu_$ f i nd_symbo 1 (block_pt, symbol, 
steps) ; 

if symbol_pt » null then return (null); 

/* determine stack frame of block owning symbol 
*/ 

sp ■ stack_pt; 

do I = 1 to steps; 

sp ■ sp-» frame, di spl ay; 

end; 
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/* determine address of symbol */ 
ref_pt ■ null; 

add_pt 88 stu__$get_address (symbol_pt, sp, 
ref_pt, subs_pt); 

if add_pt ■ null then return (null); 

/* determine size */ 

size » symbol_pt -> symbol__node. si ze; 

if size < 0 
then do; 

size ■ stu_$decode__value (size, sp, 
ref_pt, code); 

if code > « 0 then return (null); 

end; 

return (add_pt); 
end example; 



(END) 
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Name : surf i xed_name__ 

This subroutine handles suffixed storage system entry names. 
It provides an entry point that creates a properly-suffixed name 
from a user-supplied name that may or may not include a suffix, 
an entry point that changes the suffix on a user-supplied name 
that may or may not include the original suffix, and an entry 
point that finds a segment/ a directory, or a multisegment file 
whose name matches a user-supplied name that may or may not 
include a suffix. It is intended to be used by commands that 
deal with segments with a standard suffix, but that do not 
require the user to supply the suffix in the command arguments. 

Entrv : suf f i xed__name_$f i nd 

This entry point attempts to find a directory entry whose 
name matches a user-supplied name that may or may not be properly 
suffixed. This directory entry can be a segment, another 
directory, or a mul ti -segment file (MSF). 

Usage 

declare suf fixed_name_$ find entry (char(*), char(*), 
char(*), char(32) aligned, fixed bin(2), 
fixed bin(5), fixed bin(35)); 

call suf f ixed_name_$f i nd (directory, name, suffix, entry 
type, mode, code); 

1) directory is the name of the directory in which the entry is 
to be found. (Input) 

is the name that has been supplied by the user, 
and that may or may not be properly suffixed. 
(Input) 

is the suffix that is supposed to be on name. It 
should not contain a leading period. (Input) 

is a properly-suffixed version of name. It is 
returned even if the directory entry, 
d i rectory>ent ry, does not exist. (Output) 

is a switch indicating the type of directory entry 
that was found: (Output) 

0 -- no entry was found. 

1 -- a segment was found. 

2 -- a directory was found. 



2) name 

3) suffix 
h) entry 

5) type 
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3 a mul t ? -segment file was found* 

6) mode is the caller's access mode to the directory entry 

that was found. See the MPM writeup of 
hcs_$append__branch for a description of mode. 
Note that the caller's assecc mode to the MSF 
directory is returned for a multisegment file. 
(Output) 

7) code is one of the following status codes: (Output) 

0 the search was successful . 

error_table_$noentry — no directory entry that 
matches name was found. 

error_tabl e_$no__i nf o — no directory entry that 
matches name was found, and futhermore, the caller 
does not have status permission to the directory. 

error_table_$i ncorrect__access — a directory 
entry that matches name was found, but the caller 
has null access to this entry, and to the 
directory containing this entry. 

error_tabl e_$entlong — the properly-suffixed 
name that was made is longer than name. 

Entry : suf f i xed_name_$ make 

This entry point makes a properly-suffixed name out of a 
name supplied by the user that may or may not be properly 
suf f i xed. 

declare suf f i xed__name__$make entry (char(*), char(*), 
char(32) aligned, fixed bin(35)); 

call suf f i xed_name_$make (name, suffix, priper_name, code); 

1) name is as above. (input) 

2) suffix is as above. (Input) 

3) proper__name is a properly-suffixed version of name. 

k) code is one of the following status codes: (Output) 
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0 — proper name was made successfully/ 

error__tabl e_$ent 1 ong — the properly-suffixed 

name that was made is longer that proper_name. 

proper_name contains only a part of the 
properly-suffixed name. 

Entry ; suf f i xed__name_$new_suf f i x 

This entry point creates a name with a new suffix by 
changing the (possibly existing) suffix on a user-supplied name 
to the new suffix. If there is no suffix on the user-supplied 
name, then the new suffix is merely appended to the user-supplied 
name . 



Usage 



declare suf f ixed_name_$new_suf f i x entry (charC*), char(*)/ 
char(*)/ char(32), fixed bin(35)); 

call suf f i xed_name_$new_suf f i x {name, suffix/ new_ suffix/ 
new_name, code); 



1 ) name 

2) suffix 

3) new_suffix 
k ) new__name 

5) code 



is as above. (Input) 

is the suffix that may or may not already be on 
name. (Input) 

is the new suffix. (Input) 

is the name that was created. If name ends with 
.suffix, then .new_suffix replaces .suffix in 
new__name. Otherwise/ new_name if formed by 
appending .new_suffix to name. (Output) 

is one of the following status codes: (Output) 

0 -- new_ name was made successfully. 

error_tabl e_$entlong -- the properly-suffixed new 
name is longer than new__name. new__name contains 
only part of the properly-suffixed new name. 



Note 



If error_table_$no_s_permi ss ion is encountered during the 
processing for suf f i xed_name_$f i nd, it is ignored and is not 
returned in the status code. 
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Name : syn 

The synonym interface module provides a means by which two 
stream names can be made equivalent. Two stream names may be 
synonymized by the following call: 

call ios_$attach (streaml, "syn", stream2, "", status); 

Once the above call has been executed/ all I/O system 
calls, with the exception of the attach and detach calls, will be 
redirected to stream2 until the synonymi zat i on is dissolved by a 
call to detach. In other words, all such I/O calls on either 
stream will have identical results and are, therefore, 
synonymous. The synonym interface module has been heavily 
optimized. It is therefore recommended that in cases where I/O 
devices are repeatedly detached and reattached within a process, 
that this detaching and reattaching be performed with a 
synonymized stream rather than detaching and reattaching the 
devices themselves. 

JULO System Cal Is 

All I/O system calls are implemented by the synonym module. 

Peyice Identification 

The pseudo-device upon which the synonym module operates is 
simply a stream, therefore any stream name is a legitimate device 
i dent i f ier . 

Detachment 

Detachment results in the dissolution of the synonymi zat i on 
of the associated stream. No other action can be specified in 
the detach cal 1 . 

Notes 

Due to the importance of the synonym module, it has been 
given several special properties. 

The second stream name, stream2, in the call to attach does 
not have to exist at attach call time. The attachment will be 
completed anyway and, unless stream2 is subsequently attached to 
some device, an error will result when a call is made upon 
streaml. 
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Since all calls, except attach and detach, made to a stream 
attached via the synonym module are simply forwarded to the 
object or attached to stream, the synonym module has no modes, 
synchronization, element sizes, delimiters, breaks, reference 
pointers, or order calls of its own. It simply takes on the 
properties of the stream to which it is attached. The mode 
argument in the call to attach is ignored by the synonym module. 

Currently, when an attempt is made to attach a stream that 
is already attached via the synonym module, the synonym 
attachment will be automatically detached. This special feature 
is only temporary and will be removed. Users are advised not to 
take advantage of it. 
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Name ; tape_ 

This procedure Is the I/O system Device Interface Module 
(DIM) used to access magnetic tapes written in Multics standard 
tape format. (See the MPM Reference Guide section, Multics 
Standard Magnetic Tape Format.) It is not called directly by the 
user's program. Instead, the user provides the name tape_ in a 
call to the I/O system attach entry. He then accomplishes the 
I/O operations by calling standard I/O system entry points that 
are independent of the interface module being used. Further 
information on the I/O system can be found in the MPM Reference 
Guide section on Input and Output Facilities. Details about the 
I/O system call syntax can be found in the module description of 
ios_. 

Notes 

Tape label records and end of reel records are written by 
the attach/detach functions automatically. Blocking of data into 
256-word blocks is done internally by the read/write functions so 
that any number of words of data can be transmitted in a single 
cal 1 . 

Permitted 1Z£ System Cans 

attach 

detach 

gets ize 

order 

read 

seek 

wr i te 

Device identifier? 

This DIM accepts any character string of length 6 as a 
device identifier for a tape. The character string to be used 
should be agreed upon with Multics Operations when the tape is 
signed out. 

status Indications 

Only standard Multics status codes are returned in the first 
half of the status string. The following status codes can be 
returned by tape_: 

error_table_$argerr 
error_table_$bad__i ndex 
error_tabl e_$bad_label 
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e r ro rv_tab 1 e_$ bad_mode 

error_table_$bad_process id 

error_tabl e__$bad_r I ng__b rackets 

erro r_tabl e__$blank_tape 

error_table_$buf f er__big 

error_tabl e_$ da ta_Jmp roper 1 y_termi nated 

error__tabl e_$dev__of f set_out_of abounds 

error_table_$devlce_end 

error__table_$device_J imi t_exceeded 

error_tab1e_$device_par i ty 

error__table_$ improper__data_format 

error_table__$ inval id_ read 

error_table_$ i nval i d_wr i te 

error_ table__$ io_st i 1 l_assnd 

error_table_$ ionmat 

e r ro r_ta b 1 e_$mou n t_no t_r eady 

error_table__$no__devi ce 

error_table_$no_jnessage 

error__tabl e_$no__room_f or_dsb 

e r r o r_ t a b 1 e_$ no__s y s 

error_table_$not__attached 

er ror_tabl e_$ redundant_mount 

error_tabl e_$ too_many_buf f ers 

er ror_table_$undef ined__order_request 

error_table__$undef i ned_ptrname 

error_tabl e_$unimp1emented_ptrname 



Currently/ the only meaningful bits in the second half of 
the status argument are the physi cal_end_of_data bit, the 
logical_end_of__data bit, and the stream__name_detached bit. See 
the MPM Reference Guide section. Use of the Input and Output 
System, for more information. 

The phys i cal_end_of_data bit is currently turned on during 
writing when the end of a physical tape reel is reached, 
indicating that no more data can be written on the reel. 
Checking this bit is the standard way of telling whether the end 
of the reel has been reached. It is turned on during reading if 
a normal tape termination is reached and it occurs at the 
physical end of reel. (A tape is normally terminated if it was 
properly detached when written, i.e., if it contains a valid end 
of reel record.) 



The logical_end_of_data bit has no significance for writing. 
During reading, this bit is turned on when the logical end of 
data on the tape, i.e., the last relevant record, has been 
reached; the situation is further described by the status code 
portion of the status argument. For example, if the tape was not 
normally terminated, but the data is otherwise good, the code 
error__tabl e„$data_improper 1 y__term? nated is returned. 
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The stream_name_detached bit is turned on when the tape and 
the stream are detached from the process; this can happen only 
during attach or detach requests. 

Currently there are some temporary deviations from the 
standards described above with respect to the logi cal_end_of__data 
bit. It is turned on during writing, but should be ignored. 
When it is turned on during reading/ a status code of zero 
eventually will mean normal termination, although currently 
error_table_$device_end is returned in this case. 

Modes 

The only modes accepted by the attach call to tape_ are r 
(read) and w (write). Any other mode specification/ including 
rw/ results in refusal to attach the stream. 

Element size 

Only an element size of 36 is permitted. 

Order Requests 

The following order requests are implemented by this DIM: 

error__count is permitted only for tapes attached for writing. 

It writes out all currently filled write-behind 
buffers and returns the count of the total number 
of rewrite attempts in a fixed binary(35) number 
pointed to by the argptr argument of the 
ios_$order cal 1 . 

rewind is obsolete and will be removed eventually. The 

seek request should be used instead. 

Break Characters and. Read Dei imi ters 

None of these are used by tape_. All transmission is 
controlled by the nelem argument of the read/write call. The 
only nonerroneous case where nelemt differs from nelem is for end 
of data reading. 
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Seek and Tel 1 Call s 

Seek/ as currently implemented, Is very limited and intended 
for rewinding only, poi nter_name_l can be either read or write, 
pointer__name_2 must be "first"/ and offset must be 0. (See the 
MPM subroutine write-up for ios__$seek.) This causes the tape to 
be rewound without unloading and readied for use in the same mode 
as before. To change mode, the tape must first be detached/ then 
reattached in the other mode. 

Tell is not currently implemented. 

Synchronization 

This DIM operates only in read asynchronous/ write 
asynchronous mode. 

Detach ? ng 

A tape is unloaded when detached. 

Notes 

There are some aspects of the Multics standard tape format 
that are not currently implemented by tape__. There is no 
provision for handling multireel logical tapes and the 
synchronous indicator of a record header is never set. The 
padding bit pattern word used is a word consisting of all ones. 
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Name : term_ 

The procedure term_ terminates a segment. That is, it does 
the work of removing a segment from the caller's address space 
and his combined linkage section. It unsnaps links to the 
terminated routine and removes references to it (if any) from the 
command processor's memory. For the term_ entry, links to the 
segment are not unsnapped unless the segment has a linkage 
section. 

Usage 

declare term__ entry (char(*) aligned, char(*) aligned, 
fixed bin(35)); 

call term_ (dirpath, ename, code); 

1) dirpath is the path name of the parent directory of the 

segment to be terminated. (Input) 

2) ename is the entry name of the segment to be terminated. 

(Input) 

3) code is a standard status code. (Output) 

Entry : term_$ref name 

This entry allows termination of a segment by reference name 
rather than path name. For this entry, links to the segment are 
always unsnapped even if it has no linkage section. 

Usage 

declare term_$ ref name entry (char(*) aligned, 
fixed bin(35)); 

call term_$ ref name (ref name, code); 

1) ref name is the reference name of the segment to be 

terminated. (Input) 

2) code is a standard status code. (Output) 
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This entry allows termination of a segment referenced by a 
pointer. Links are not unsnapped unless the segment has a 
1 i nkage secti on. 

Usage 

declare term_$seg_ptr entry (ptr, fixed bin(35)); 
call term_$seg_ptr (segptr, code); 

1) segptr is a pointer to the segment to be terminated. 

(Input) 

2) code is a standard status code. (Output) 

Fntry : term_$unsnap 

This is a special entry identical to the nomakeunknown entry 
execpt that links to the segment are always unsnapped even if it 
has no linkage section. 

Usage 

declare term_$unsnap entry (ptr, fixed bin(35)); 
call term_$unsnap (segptr, code); 
Arguments are as above. 
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Entry : term_$si ngl e_ref name 

This entry allows termination of a single reference name. 
The segment is not terminated unless the specified reference name 
was the only reference name by which it was known. Links to the 
segment are always unsnapped even if it has no linkage section. 

Usgge 

declare term_$si ngl e_ref name (char(*) aligned, 
fixed bin(35)); 

call term_$si ngle_ref name( ref name, code); 

1) refname is the reference name to be terminated. (Input) 

2) code is a standard status code. (Output) 
Notes 

The possible status codes returned are: 

1) er ror_tabl e_$ i nval i dsegno; 

2) er ror_table_ $seg_ unknown; 

3) error_table_ $nolot ; 
k) er ror_tab 1 e__$ lo ter r . 

The subroutine hcs__$ termi nate_f i 1 e performs the same 

operation as does term , but provides an additional option; 
hcs_$termi nate_seg is the same as term_$seg_ptr with an 
additional option; and hcs_$termi nate performs the same operation 
as term_$si ngl e_ref name. 
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Name : t imer_manager_ 



The timer manager is provided to fulfill a specialized need 
of certain sophisticated programs. A user should be familiar 
with Interprocess Communication in Multics and the pitfalls of 
writing programs which may run asynchronously within a process. 
These pitfalls may be avoided by using only the 
timer_ manager_$s 1 eep entry. 

The timer manager allows many cpu usage timers and real time 
timers to be used simultaneously by a process. The caller may 
specify for each timer whether a wakeup Is to be issued or a 
specified procedure is to be called when the timer goes off. 



generic Arguments 

1) channel is the name of the event channel (fixed 

binary(7D) over which a wakeup is desired. 
Two or more timers may be running 
simultaneously/ all of which may, if desired/ 
issue a wakeup on the same event channel. 

2) routine is a procedure entry point (entry) that will 

be called when the timer goes off. The 
routine will be called this way: 

declare routine entry (ptr/ char(*)); 

call routine (mcptr, name); 

1) mcptr is a pointer to a structure 

containing the machine conditions 
at the time of the process 
interrupt, (input) 

2) name is alrm for a real time timer and 

is cput for a cpu timer. (Input) 

(See signal., for a full description of these 
arguments.) Two or more timers may be 
running simultaneously/ all of which may/ If 
desired/ call the same routine. 



3) time is the time (fixed binary(7D) at which the 

wakeup or call is desired. 
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in just what way time is to be interpreted. 
The high order bit indicates whether it is an 
absolute or a relative time. The low order 
bit indicates whether it is in units of 
seconds or microseconds. Absolute real time 
is time since January I, 1901/ 0000 hours 
Greenwich Mean Time (GMT)/ i.e./ the time 
returned by clock... Absolute cpu time is 
total time used by the process/ i.e./ the 
time returned by hcs_$get_usage_va1 ues. 
Relative time is time from when 
timer — manage r__ was called. 

"ll"b means relative seconds 

"10"b means relative microseconds 

"01"b means absolute seconds 

"00"b means absolute microseconds 

Entrv : t i mer.jnanager_$s 1 eep 

This entry point causes the process to go blocked for a 
period of real time. Other timers that are active will continue 
to be processed whenever they ring; however/ this routine will 
not return until the real time has been passed. 

Usage 

declare timer^manager^sleep entry (fixed btn(71), blt(2)); 

call t imer_manager_$sl eep (time/ flags); 

The time is always real time; however/ it may be relative or 
absolute/ seconds or microseconds/ as explained in the Generic 
Arguments. 

Entrv : t i mer_manager__ $a 1 arm_eal 1 

This entry sets up a real time timer that will call the 
routine specified when the timer goes off. 

Usage 

declare timer — managerial arm_cal 1 entry (fixed bin(71)/ 
bit(2)/ entry); 



call timer_manager_$alarm_ cal 1 (time/ flags/ routine); 
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Entrv : t i me r_manage r_$a 1 a rm — cal l_i nhi bi t 

This entry sets up a real time timer that will call the 
routine specified with all interrupts inhibited when the timer 
goes off. When the interrupt is returned from, interrupts will 
be re-enabled. If the interrupt is not returned from, interrupts 
will not be re-enabled. 

Usage 

declare timer $manager $a1 arm__cal l_i nhl bi t entry (fixed 
bin(71), bit(2), entry); 

call timer_manager_$alarm — cal l_i nhl bi t (timer, flags, 
rout i ne) ; 

Entrv : t imer_manager_$al arm_ wakeup 

This entry sets up a real time timer that will issue a 
wakeup on the event channel specified when the timer goes off. 
The event message passed is alar m . 

Usage 

declare timer — managerial a rm_wakeup entry (fixed bln(71), 
bit(2), fixed bin(71)); 

call t imer_manager_$alarm_wakeup (time, flags* channel); 

Entrv : timer_manager - _$cpu_cal 1 

This entry sets up a cpu timer that will call the routine 
specified when the timer goes off. 

Usaae 

declare timer — manager_$cpu_cal 1 entry (fixed b!n(71), 
bit(2), entry); 

call t imer_manager_ $cpu_cal 1 (time, flags, routine); 

Entrv : t i mer_jnanager_$cpu_cal 1 I nh i b i t 

This entry sets up a cpu timer that will call the routine 
specified with all interrupts inhibited when the timer goes off. 
When the interrupt is returned from / interrupts will be 
re-enabled. If the interrupt is not returned from, interrupts 
will not be re-enabled. 
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declare t imer_manager_$cpu_cal 1_ I nhi b 1 1 entry (fixed 
bin(71), bit(2), entry); 

call timer_manager_$cpu_cal l_j nhl bi t (time/ flags, 
rout i ne) ; 

Entrv : t imer_manager_$cpu_wakeup 

This entry sets up a cpu timer that will issue a wakeup on 
the event channel specified when the timer goes off. The event 
message passed is cpu__time. 

Usage 

declare t imer_manager — $cpu_ wakeup entry (fixed bin(71), 
bit(2), fixed bin(71)); 

call t imer_manager_$cpu_wakeup (time, flags, channel); 

Entrv ; t imer_manager__$reset_cpu_cal 1 

This entry turns off all cpu timers that will call the 
routine specified when they go off. 

Usage 

declare t imer__ manager_$reset_cpu_ ca 1 1 entry (entry); 

call t imer_manager_$reset_cpu — cal 1 (routine); 

Entrv : t imer_manager_$reset_cpu_ wakeup 

This entry turns off all cpu timers that will issue a wakeup 
on the event channel specified when they go off. 

declare t imer — manager_ $reset_cpu_wakeup entry (fixed 
bin(71)); 

call t imer__ manager_$reset_cpu_wakeup (channel); 

Entrv : t imer_manager_$reset__ al arm_cal 1 

This entry turns off all real time timers that will call the 
routine specified when they go off. 
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declare t imer_manager_$reset_al arm_cal 1 entry (entry); 

call timer_manager._$reset_al arm_ca1 1 (routine); 

Entry ; timer_ manager__$reset_ al arm__wakeup 

This entry turns off all real time timers that will issue a 
wakeup on the event channel specified when they go off. 

Usage 

declare timer manager_$reset_al arm_wakeup entry (fixed 
bin<71)); 

call timer_manager_$reset_ alarm_wakeup (channel); 

NPtes 

For most uses of t imer.jnanager_, a cleanup condition handler 
should be set up that will reset all the timers that might be set 
by a system of programs. This way, if the system is aborted and 
released, any timers set up by the system will be reset instead 
of going off at undesired times. 

In order to be used, t imer_manager_ must be established as 
the condition handler for the conditions alrm and cput. This is 
done automatically by the standard Multics environment. 
Subsystems which do not use the standard environment should make 
the following calls when establishing their environment: 

call condition,, ("alrm", timer_manager_$al arm_J nter rupt ) ; 

call condition^, ("cput 11 , 

timer_manager — $cpu_timer_i nterrupt) ; 



(END) 
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Name ; total_cpu__t ime_ 

This procedure returns the total CPU time used by the 
calling process since it was created. The time includes time 
spent handling page faults, segment faults, and bound faults for 
the calling process as well as time spent handl i ng any system 
interrupt which occurred while the calling process was executing. 



usage 



declare total_cpu_t i me_ entry returns (fixed bin (71)); 



time = total__cpu_t ime_( ) ; 



1 ) t i me 



is the total CPU time, in microseconds used by the 
calling process. (Output) 
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NflPie: tw_ 

This procedure is the I/O System Interface Module ( I OS I M) 
used to control operation of a console typewriter. It is not 
directly called by a user program. Instead / the user provides 
the name tw_ in a call to the I/O system attach entry. He then 
accomplishes the I/O operations by calling standard I/O system 
entry points that are independent of the interface module in use. 
Further information on the I/O system can be found in the MPM 
Reference Guide section on I/O and details of the I/O system call 
syntax can be found in the subroutine description for ios_. This 
write-up explains how the subroutine tw__ interprets the standard 
I /0 system cal 1 s . 

Usage 

call ios_$attach (stream_name, "tw_ fl , ttychan, mode, 
status ); 

The normal sequence of process initialization for a local 
dialup user includes a call to attach the user's typewriter 
through tw_ to the stream "user_i /o" . Thus, the casual user need 
not concern himself about performing the attach call himself 
unless he is performing some special operation such as attaching 
a second typewriter to his process. However, the remainder or 
this section might still be of interest since it details the way 
in which the module tw_ interprets the standard I/O system calls 
directed to the stream "user_i/o n and any other streams that are 
attached to "user_l /o". 

Notes 

This I0SIM supports all devices used as local consoles in 
the Multics system. It expects the device to have both an input 
(usually a keyboard) and an output (a printer or a video display) 
device. The devices currently supported include the IBM 1050, 
IBM 2741, Bell model 33, 35, 37, and 38 Teletypes, ARDS, GE 
Terminet 300, Datel 30, and any devices presenting an interface 
to the system equivalent to any of the above. 

Most data presented to the I OS I M should be standard Multics 
character strings (sequences of 7-bit Multics character codes 
right adjusted in 9-bit fields). Conversion to the character 
code of the device is performed automatically by the I0SIM. The 
exceptions occur when in raw input or output mode (see Modes 
below) or when in graphic input or output mode when communicating 
with graphic devices. In normal operation, the I OS I M performs 
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standard M u 1 tics canon I cal ? zat i on and erase-and-ki 1 1 processing 
as described in the MPM Reference Guide section/ Typing 
Conventions. Tab positions on all terminals are assumed to be 
placed in every tenth character position and automatically 
replace spaces, when appropriate, on output. 

Part of the Multics quit mechanism is included in this 
I0SIM. When the key or keys on the terminal designated as the 
quit key are activated, the I OS I M immediately aborts and discards 
input or output currently being performed on this terminal and 
echoes a new line character. It then sends a quit interrupt to 
the process that currently owns this terminal. If the process 
signalled is in the standard Multics command environment, the 
computation in progress is suspended and the process returns to 
command level. 

Permitted I/O System Call? 

The following I/O system calls are implemented by this 
I0SIM: 

abort 

attach 

changemode 

detach 

gets i ze 

order 

read 

resetread 
resetwr i te 
wr i te 

Device identifiers 

Terminals handled by this I OS I M are usually connected to the 
system via telephone lines; therefore the identifiers presented 
to the I OS I M at attach time correspond to channels connected to 
particular lines rather than to the actual device. Therefore, 
the same terminal can have different device identifiers in 
different terminal sessions. Channel identifiers are character 
strings of up to six characters. 

Hodes 

The following modes can be specified in calls to attach and 
changemode. 
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erkl 



can 



raw i 



rawo 



tabs 



ed i ted 



specifies that erase-and-ki 1 1 processing is 
to be performed on input. (Default is on.) 



indicates that standard canon i cal i zati on 
to be performed. (Default is on.) 



! s 



indicates that the data specified is to be 
read from the device directly without any 
conversion or processing. (Default is off.) 

indicates that data is to be written to the 
device directly without any conversion or 
processing. (Default is off.) 

indicates that tabs are to be inserted in 
output in place of spaces when appropriate. 
(Default is off for model 33, 35 and 38 
teletypes; default is on for all other 
terminal types). 

causes printing of characters for which there 
is no defined Multics equivalent on the 
device referenced to be suppressed. If 
edited mode is off, the 9-bit octal 
representation of the character is printed. 
(Default is off.) 



esc enables escape processing (see the MPM 

Reference Guide section, Typing Conventions) 
on all input read from the device. (Default 
is on . ) 

red specifies that red and black shifts are to be 

sent to the terminal. (Default is off for GE 
terminet 300s and for all terminals without 
an answerback identifier; default is on for 
all other terminals.) 



crecho specifies that a carriage return is to be 

echoed when a line feed is typed. (Default 
is off; this mode is only functional with 
model 33, 35, 37, and 38 Teletypes and with 
GE Termi net 300s. ) 

lln specifies the length in character positions 

of a console line. If an attempt is made to 
output a line longer than this length, the 
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excess characters are placed on the next 
line. (Default line length is 130 for I PM 
1050s, 125 for IBM 2741s, 88 for TTY37s, 118 
for Terminet 300s, for ARPS, 7k for TTY33s 
and TTY35s, and 125 for TTY38s.) 

pin. specifies the length in lines of a page. 

When an attempt is made to exceed this 
length, an ARDS "DEL 11 character is printed; 
when the user types an erase character, the 
output continues wi th the next page. This 
mode is functional only for ARDS terminals. 
(Default page length is 50 for ARPS.) 

hndlquit specifies that when a quit is detected, a new 

line character is echoed and a resetread of 
the associated stream is performed. (Default 
is on. ) 

default is a shorthand for erkl, can, ""Yawi, "Yawo, 

and esc. The settings for other modes are 
not affected. 

Returned Status 

Only standard Multics error codes are returned as the first 
half of the status string. The first half of the status string 
being nonzero indicates an error. At present, none of the bits 
in the second half of the status string are meaningful. 

Order Requests 

The following order requests are implemented by this DIM: 

hangup causes the telephone line connection of the 

terminal to be disconnected, if possible. 

listen cause a wakeup to be sent to the process if 

the line associated with this device IP is 
dialed up. 

info causes information about the device to be 
returned. The pointer argument should point 

to the following structure that is filled in 
by the cal 1 . 
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declare 1 i nfo_st ructure aligned, 
2 id char(U) unaligned, 
2 reserved char(8) unaligned, 
2 tw__type fixed bin; 

1) id is the identifier of the specific device as told 

to Multics by the device when the device is 
ini tial ized. 



2) reserved 

3) tw_type 



is space reserved for compatibility purposes, 
identifies the type of device: 

1 = IBM 1050; 

2 = IBM 2741 (with M.l.T. modifications); 

3 = Teletype model 37; 

4 = Terminet 300; 

5 = ARDS; 

6 = IBM 2741 (standard); 

7 - Teletype models 33 or 35; 

8 s Teletype model 38. 



qu i t_enabl e 



qu i t_di sable 



start 



pr i nter_of f 



pr i nter_on 



causes quit processing to be enabled for this 
device. (Quit processing is initially 
di sabled. ) 

causes quit processing to be disabled for 
this device. 

causes a wakeup to be signalled on the event 
channel associated with this device. This 

request is used to restart processing on a 
device whose wakeup may have been lost or 
di scarded . 

causes the printer mechanism of the console 
to be temporarily disabled if it is 
physically possible for the terminal to do 
so . 

causes the printer mechanism of the terminal 
to be re-enabled. 



F 1 ement S i ze 

Only an element size of nine is permitted. 
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Break Characters and Read Del I ml ter s 

The only permitted break character and read delimiter is the 
new line character. There is currently an implementation 
restriction such that new line characters that have been typed in 
as escape sequences are not recognized as read delimiters. 

Synchronization 

This DIM operates only in read asynchronous/ write 
asynchronous, workspace synchronous mode. The limits of 
read-ahead and v/r i te-beh i nd are determined by the I OS I M at call 
time and are dependent upon the load on the I OS I M by all of its 
users on the system and, therefore, can vary from call to call. 
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Name ; unique__bi ts_ 

This subroutine returns a unique bit string useful as an 
identifier. It is obtained by reading the system clock which 
returns the number of microseconds elapsed since January 1, 1901, 
0000 hrs GMT. The bit string is unique among all bit strings 
obtained in this manner in the history of a Multics installation. 

Usage 

declare unique_bi ts__ entry returns (bit(70)); 
bit_string = unique_b? ts_( ); 
1) bit_string is the unique bit string. (Output) 
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Name : un i que__chars__ 

The procedure un i que__bi ts_ provides the user with a source 
of bit-string identifiers guaranteed to differ from all other 
identifiers generated by that procedure. The procedure 
un i que__chars_ provides a character string representation of such 
a uni que bi t str i ng. 

Usage 

declare un i que_chars_ entry (bit(*)) returns (char(15)); 
char_string = uni que_chars__(bi ts ) ; 

1) char_string is a unique character string. (Output) 

2) bits is a bit string of up to 70 bits. (Input) 
Notes 

If the bits argument is less than 70 bits in length/ 
unique_chars_ pads it with zeros on the right to produce a 70-bit 
string. If the bits argument equals zero, uni que_chars_ calls 
uni que_bi ts_ to obtain a unique bit string. Note that if the 
bits argument is supplied (non-zero) and is not a unique bit 
string/ the character string returned by uni que__chars_ cannot be 
guaranteed to be unique. 

The first character in the character string produced is 

always ! (exclamation point) to identify the string as a unique 

identifier. The remaining 1** characters/ forming the unique 

identifier/ are alphanumeric. All vowels are omitted to avoid 
accidently forming a name likely to be chosen by a person. 
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Name ; unpack__system_code_ 

This procedure must be used to convert certain packed status 
codes, returned by system procedures using ^nonstandard status 
codes, into Multics standard status codes, which may be used in 
calling com_err_ or comma nd_q ue r y_, or which may be compared with 
codes defined in the standard status code table. (See the MPM 
Reference Guide sections on Strategies for Handling Unusual 
Occurrences and List of System Status Codes and Meanings. See 
also the MPM Subroutines section for the write-ups of com_err_ 
and command_query_. ) 

unpack__system_code_ converts bit strings of length greater 
than 12 and less than 36 which have been returned by such 
procedures as hcs_$acl_add, hcs_$acl_de 1 ete, hcs_$acl__l i s t, and 
hcs_$acl_repl ace to fixed binary(35) aligned values. (See the 
MPM Subroutines section for the aforementioned procedures.) 

Those procedures which use nonstandard packed status codes 
will be phased out in the future, at which time all status codes 
will be stored in standard form. unpack_sys tem_code_ will no 
longer be required then. 

Usage 

declare unpack_sys tem_code__ entry CbitC*) unaligned) 
returns (fixed bin(35) aligned); 

code = unpack_sys tem_code_ ( pack_code ) ; 

1) pack_code is a packed code. For an example of a packed code, 

see the document on hcs_$acl _add. (Input) 

2) code is the standard status code corresponding to the 

packed value given. (Output) 

Notes 

This procedure will only work for packed codes returned by 
system subroutines. There is no way to pack user-defined 
standard status codes into less than 36 bits. 
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Name ! user__info_ 



This procedure allows the user to obtain information 
concerning his login session. 

Entry : user_info_ 

This entry returns the user's login name, project id, and 
account id. 

Usage 

declare user_info_ entry (char(*)/ char(*), char(*)); 
call user_info_ (name, proj, acct); 

1) name is the user's name from the login line (maximum of 

22 characters). (Output) 

2) proj is the user's project ID (maximum of 9 

characters). (Output) 

3) acct is the user's account ID (maximum of 32 

characters). (Output) 

Entrv : user_i nfo_$whoami 

This is the same as the user_info_ entry point. The added 
name is for mnemonic convenience. 

Usage 

declare user_i nf o_$whoami entry (char(*) / char(*), 
char (*) ) ; 

call user_i nfo_$whoami (name, proj, acct); 

Arguments are as above. 

Entry : user__i nfo_$ log in_data 

This entry returns useful information about how the user 
logged in. 
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Usage, 



declare user_j nfo_$ logi n_data entry (char(*), char(*), 
char(*), fixed bin, fixed bin, fixed bin, 
fixed bin(71), char(*)); 

call user_i nfo_$ logi n_data (name, proj, acct, anon, stby, 
weight, time_login, login_word); 



1) name 

2) proj 

3) acct 
k) anon 

5) stby 

6) weight 



is as above. (Output) 
is as above. (Output) 
is as above. (Output) 

■ 1 if the user is an anonymous user. (Output) 

= 1 if the user is standby (i.e., may be 
preempted). (Output) 

= 10 times the user's weight. (Output) 



7) time_login is the time the user logged in. It is expressed 

as a calendar clock readirg in microseconds. 
(Output) 

8) login_word is login or enter, reflecting which command the 

user logged in by. (Output) 

Entry : user_i nfo_$usage_data 

This entry returns user usage data. 

Usage 

declare user_i nfo_ $usage__data entry (fixed bin, 

fixed bin(71), fixed bin(71), fixed bin(7D); 

call user_J nfo__$usage_data (nproc, old_cpu, 
time__login, t ime_create) ; 



1) nproc 

2) old_cpu 



is the number of processes created for this login 
session. (Output) 

is the CPU time used by previous processes in the 
login session. (Output) 
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3) time_Jogin is the time of login. (Output) 

k) time_create is the time the process was created. (Output) 

Entry : user_i nfo_$homedi r 

This entry returns the path name of the user's initial 
working directory. 

Usage 

declare user_i nfo_$homedi r entry (char(*)); 

call user_i nfo_$homedi r (hdir); 

1) hdir is the path name of the user's home directory 

(maximum of 64 characters). (Output) 

Entry : user__i nf o_$ responder 

This entry returns the name of the user's login responder. 

Usage 

declare user_J nfo_$ responder entry (char(*)); 

call user__i nfo__$ res ponder (resp); 

1) resp is the name of the user's login responder (maximum 

of 64 characters). (Output) 

Entry : user_i nfo_$ tty_data 



This entry returns information about the user's process' 
termi nal . 



Usage 



declare user_i nfo_$ tty_data entry (char(*), fixed bin, 
char(*) ) ; 

call user_info_$tty_data (idcode, type, channel); 
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1) idcode is the terminal ID code of the user's (maximum of 

k characters). (Output) 

2) type is the type of terminal: 

0 ■ absentee process or network user; 

1 = IBM 1050; 

2 = IBM 2741 (with MIT modifications); 

3 = Teletype Model 37; 
h = Terminet 300; 

5 = ARDS; 

6 = IBM 2741 (unmodified); 

7 = Teletype Model 33/ Model 35. (Output) 

3) channel is the channel identification (maximum of 8 

characters). (Output) 

Entry : user_i nf o_$ logout_data 

This entry returns the event channel over which logout is to 
be signalled and the process ID to which the signal is to be 
di rected. 

Usage 

declare user_i nf o_$ logout_data entry (fixed bin(71), 
bi t(36) al igned); 

call user_J nfo_$logout_data ( logout_channel , logout_pid); 

1) logout_channel is the event channel over which logouts are 

to be signalled. (Output) 

2) logout_pid is the process ID of the answering service. 

(Output) 

Entry : user_i nf o_$abs i n 

This entry returns the path name of the absentee input 
segment for an absentee job. For an interactive user it is 
returned as blanks. 

Usage 

declare user_J nfo_$absi n entry (char(*)); 
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call user__info__$absi n (path); 

1) path is the path name of the absentee input 

segment. (Output) 

# 

Entry : user__i nfo_$absou t 

This entry returns the path name of the absentee output 
segment for an absentee job. For an interactive user it is 
returned as blanks. 

Usage 

declare user_i nfo_$absout entry (char(*)); 

call user_J nfo_ $absout (path); 

1) path is the path name of the absentee output 

segment. (Output) 

Entry ; user_i nfo_$ 1 imi ts 

This entry returns the per-user limit values established by 
the user's project administrator/ and the user's spending against 
the 1 imi ts . 

If a limit is specified as open/ the limit value returned is 
1.0e37. 

Usage 

declare user_i nfo_$ 1 i mi ts entry (float bin, float bin, 
fixed bin(71)/ fixed bin, (0:7) float bin, 
float bin/ float bin, (0:7) float bin); 

call user_i nfo_$l imi ts (mlim/ clirri/ cdate, erf, shlim/ 
msp/ csp/ shsp); 

1) mlim is the month limit in dollars. (Output) 

2) clim is the cutoff limit in dollars. (Output) 

3) cdate is the cutoff date. (Output) 
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i*) erf is the cutoff refresh code. This indicates 

what will happen at the cutoff date: 

0 - permanent cutoff 

1 - add one day 

2 - add one month 

3 - add one year 

k - add one calendar year 

5 - add one fiscal year. (Output) 

5) shlim is the array of shift limits in dollars. 

(Output) 

6) msp is the month-to-date spending in dollars. 

(Output) 

7) csp is the spending against the cutoff limit in 

dollars. (Ouput) 

8) shsp is the spending against shift limits in 

dollars. (Output) 

Note 

All entries which take more than one argument will count 
their arguments and not attempt to return more values than there 
are arguments. 
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Name : write_list_ 

This procedure is used to print out on the user's terminal 
the values of internal variables with two spaces between 
succeeding values. The data to be written out must be one of the 
five types: real decimal fixed-point number, real decimal 
floating-point number, bit-string, character-string, or pointer. 

Since this procedure can be called with a varying number of 
arguments, it is not permissible to include a parameter attribute 
list in the declaration of the various entry points. 

Usa ge 

declare write_list entry options (variable); 

call write_list_ (argl, arg2, argn); 

1) argi is any variable of one of the five types listed above. 
(Output) 

Entrv : wr ? te_l i s t_$nnl 

This entry is identical in usage and output to write_list_, 
except that no new line character is appended to the output 
str i ng. 

usage 

declare wr i te_l i st__$nn1 entry options (varible); 
call wr i te_l ist_$nnl (argl, arg2, argn); 
Arguments are as above. 

Notes 

The maximum number of arguments is Sk, 

The data type of each argument is obtained from the 
descriptor, and conversion takes place to transform the value of 
each argument to its appropriate character string representation 
on the terminal. 

A real decimal floating-point number is printed in E format, 
with 8 decimal places for a single precision number and 19 
decimal places for a double precision number. 
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A character string is printed without the enclosing quotes. 

Example 

The following procedure produces the output indicated below, 
x: proc; 

declare a float, b char(5), c bit(3), d fixed bin; 
declare s float/ m fixed bin; 

declare write_list_ external entry options (variable); 
• 

call write__list_ (a,b,c,d); 

call write_list_ ("x=", s, "m=", m); 
• 

end x; 

The two lines printed on the terminal are: 
)6|6O.175OOOOOe-OU0i6nameJ6^t5 ,l lOl ,, b)6^-5 
*Wx=l6tf-0. 212OOOOOe+O3|6|6m=|603192 
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I N D E X 

This Index covers only Part II of the manual, namely the 
Reference Guide sections 1 to 8, and the command and subroutine 
wr i te-ups. 

jKg Index is organized around the numerical !y ordered 
Reference Guide sections and the alphabetically ordered commands 
and subroutine write-ups, rather than by page number. Thus, for 
example, the entry for bulk input and output might read: 

bulk I/O 
3.4 
k.k 

dpri nt 
dpunch 

The first two items under bulk I/O refer to the Reference Guide 
sections 3.4 and k.k, and the last two to the write-ups for the 
dprint and dpunch commands. They are referenced in the order 
that they appear in this manual. Note that command names can 
normally be distinguished from subroutines by the trailing 
underscore in the segment name of subroutines. 

Some entries are of the form: 

I/O (bulk) 

see bulk I/O 

For simplicity of usage, these entries always refer to other 
places in the Index, never to normal Reference Guide, command or 
subroutine write-ups. 

Some entries are followed by information within parentheses. 
This information serves to explain the entry by giving a more 
complete name or the name of the command under which the actual 
entry can be found. For example: 

e (enter) 

1 i stnames (list) 
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In addition to this Index., other indexes to information are: 

1) MPM Table of Contents 

- lists names of commands and subroutines with write-up issue 
dates 

- lists commands and subroutines documented under other 
write-ups; e.g., console__output : see file_output 

2) Reference Guide Section 1.1: The Multics Command Repertoire 

- lists commands by function 

3) Reference Guide Section 2.1: The Multics Subroutine 
Repertoi re 

- lists subroutines by function 

k) Reference Guide Section 8.3: Obsolete Procedures 
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I convention 

see unique strings 

* convention 

see star convention 

3. 6backup 
3.5 

7-punch cards 

see seven-punch cards 



expand_path__ 
see directories 

= convention 

see equal convention 

> 

expand_ path_ 
see directories 
see root directory 

abbrevi at ions 
1.6 

abbrev 
do 

see alternate names 
see command processing 

ABEND 

see error handling 

absentee usage 
1.8 
1.9 
1.10 
1.11 
1.12 
1.13 
1.1k 
1.15 
alm_abs 

cancel_abs__request 
enter_abs_request 
exec_com 
fortran_abs 
how_many_ users 
(cont i nued) 



absentee usage 

(cont i nued) 
1 i st_abs_requests 
pi l_abs 
runof f_abs 
who 

abs i n 

see absentee usage 

absolute path names 
expand_path_ 
see path names 
see storage system 

access control 
see protection 

access control list 
3.3 
3.1* 

deleteacl 

deletecaci (deleteacl) 
1 i stacl 

1 i stcacl ( 1 i stacl ) 
setacl 

setcacl (setacl ) 

cv_acl_ 

cv__di r_a c 1 _ 

cv_di r_mode_ 

cv_mode_ 

cv_user i d_ 

hcs_$add_acl_entr ies 

hcs_$add_d i r_acl _ent r i es 

hcs_$delete_acl_ent r i es 

hcs_$delete_di r_acl_entr i es 

hcs_$ 1 i st_acl 

hcs_$l i st_di r_acl 

hcs_$ repl ace_acl 

hcs_ $replace__di r_acl 

see protection 

account i ng 

resource_usage 

user (Active Function) 

cpu_t i me_and_pag i ng_ 

user_i nfo__ 

see metering 
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ACL 

see access control list 

active functions 
l.ii 
1.8 
1.9 
1.10 
1.11 
1.12 
1.13 
1.14 
1.15 

act i ve_ f nc_err_ 

address reuse 
hcs__$ i n i t i ate 
hcs_$ i n i t i ate__count 
hcs_ $ termi nate__f i le 
hcs_$terminate__name 
hcs_$ termi nate_noname 
hcs__$termi nate_seg 

address space 
3.2 
bind 

get_pathname (Active Function) 

new_proc 

termi nate 

where 

hcs_$delentry_seg 
h c s_$ f s__ge t_r e f_n ame 
hcs $fs get seg ptr 
hcs_$ i ni tiate 
hcs__$ i ni t i ate_count 
h c s_$ ma k e_p t r 

hcs__$ makers eg 

hcs_$ termi nate_f i le 

hcs_$ termi nate__name 

hcs_$termi nate_noname 

he s_$ te rm i na t e_s eg 

see directory entry names 

aggregate data 
5.4 

alarms 

time r__manager_ 
see clocks 
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al gol 
7.2 

al i ases 

see directory entry names 

aim 

alm_abs 

alternate names 

see directory entry names 

anonymous users 
1.2 
enter 

user (Active Function) 
user_i nfo_ 

answering questions 
answer 

APL 

apl 

archive segments 
5.5 

arch i v i ng 
archi ve 
arch i ve_sort 
reorder_arch i ve 

ARDS display 
see graphics 
see terminals 

argument count 
5.4 
cu_ 

argument descriptors 
5.4 

decode__descr i ptor__ 

argument list pointer 
5.4 
cu_ 
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debug 

trace_stack 
cu_ 

decode_descr i ptor__ 

arithmetic operations 
1.10 

divide (Active Function) 
minus (Active Function) 
mod (Active Function) 
plus (Active Function) 
times (Active Function) 

array data 
5.k 

ASCI I 
5.1 
5.2 

asking questions 
1.1k 
answer 

query (Active Function) 
response (Active Function) 
comma nd__q u e r y_ 

assembly languages 
8.5 
aim 

attach table 
k.2 

pr i n t_a t tach__tab 1 e 
ios_ 

see I/O attachments 

attachments 

see I/O attachments 

attent i on 

see process interruption 

author 
3.3 

status 

hcs_$star_ 

hcs_$status_ 
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automatic logout 
see logging out 

automatic variables 
see stack segments 

background jobs 

see absentee usage 

base conversion 
see conversion 

BASIC 
7.2 
bas i c 
bas i c_run 
bas i c_system 
pr i nt_dartmouth_l ibrary 
set_dartmouth__l i brary 
v5bas i c 

batch processing 

see absentee usage 

bi ndi ng 
arch i ve 
bi nd 

pr i nt__bi nd_map 
make__obj ec t_map_ 
see 1 i nki ng 

bit counts 
3.3 

ad j us t_b i t_count 
set_bi t_count 
status 

adjust_bi t_count_ 

decode_object_ 

hcs_$ i n i t i ate_count 

hcs_$set_bc 

hcs_$set_bc_seg 

hcs_$star_ 

hcs_$s tatus_ 

bit-string data 
5.1j 

blocks 

see interprocess communication 
see storage management 
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brackets 

see command language 
see protection 

branches 

see directories 
see segments 

break 

see process interruption 

breakpoi nts 
debug 

brief modes 

change_er ror_mode 
ready_of f 

broadcast i ng 
broadcast_ 

bulk I/O 
4.1 
k.k 
5.3 

cance l_daemon_reques t 

con sol e_output 

dpr int 

dpunch 

f i 1 e_output 

1 i st_daemon_requests 

nstd__ 

cancel 1 i ng 

cance l_abs_request 
cance l_daemon_request 
see deleting 

canonical ization 
1.3 
tw__ 

card formats 

cards 

see I/O 

see punched cards 
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catalogs 

see directories 

see directory entry names 

changing names 

see directory entry names 

changing working directory 
see working directory 

character codes 
1.3 
5.1 
5.2 



character formats 
5.1 



character string operations 
1.11 

index (Active Function) 
length (Active Function) 
substr (Active Function) 

character string output 
ioa_ 
ios_ 

wr i te__l i st__ 

character string segments 
5.5 



character-string data 
S.k 

checking changes 
check_i nf o__segs 

checksum 
S.k 

cleanup tools 
6.2 
6.3 

adjust_bi t_count 
close_f i le 
compare 
compare_asci i 
d i spl ay__component__name 
(cont i nued) 
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cleanup tools 

(cont i nued) 
f s_chname 
new_proc 
release 
set_b i t_count 
termi nate 
truncate 

adjust_bi t_count_ 

hcs_$set_bc 

h c s_$ s e t_b c_s e g 

hcs_$ termi nate_f i le 

h c s__$ t e r m i n a t e__n ame 

hcs_$ termi nate_noname 

hcs__$ termi nate_seg 

hcs__$ truncate_f i l e 

hcs_$truncate__seg 

term_ 



command environment 
Section 1 
l.k 

command language 
l.k 
1.8 

1.9 

1.10 

1.11 

1.12 

1.13 

1.1k 

1.15 

abbrev 

get__com_l i ne 
set_com_J i ne 
see command processing 



clocks 
2.6 

clock__ 

convert_date_to_binary. 
date_t ime_ 
decode__clock__val ue — 
t i me r_manage r__ 

clos i ng f i les 
close_f i le 
see bit counts 
see termination 

code conversion 
see conversion 

coding standards 
2.5 

collating sequence 
5.1 
5.2 

sort_f i le 

combined linkage segment 
3.1 

combining segments 
archi ve 
bi nd 



command level 
1.* 
cu_ 

command names 
1.5 

abbrev 

see directory entry names 
see searching 

command processing 
1.3 

abbrev 
do 

enter_abs_reques t 
exec_.com 
get__com_l i ne 
set_com__l i ne 
wal k_subtree 
act i ve_f nc_er r_ 
cu_ 

hcs_$star_ 

see active functions 

see searching 

command utility procedures 
cu_ 

commands 
1.1 

(cont i nued) 
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commands 

(cont i nued) 
l.h 
1.6 

Section 9 

see command processing 

comparing character strings 
equal (Active Function) 
greater (Active Function) 
less (Active Function) 

comparing segments 
compare 
compare_asci i 

compi 1 ers 

see languages 

complex data 
S.k 

condition names 
1.5 

condi t i ons 
6.1 
6.2 
6.3 
6.5 

change__error__mode 

program_i nterrupt 

repr int_error 

act i ve_f nc_err_ 

com_e r r_ 

cond i t ion_ 

f i nd__cond i t ion_i nfo_ 

revers ion_ 

s i gnal_ 

see cleanup tools 

see process interruption 

see unwinding 

console line length 

see terminal line length 

console output 
see I/O 

see interactive f/0 
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consoles 

see terminals 

control characters 
1.3 
5.1 
ioa_ 

see character codes 

convers i on 
com_e r r_ 

convert__b i nary_i nteger__ 

convert_date_to_ bi nary_ 

cv_b i n_ 

cv_dec_ 

cv_f loat_ 

cv__oct__ 

date_time_ 

decode_cl ock__va 1 ue__ 

read_l i st_ 

wr i te_l i st_ 

see formatted I/O 

see I/O 

copy swi tch 
3.3 

hcs_$ i ni t i ate 
hcs_$ i n i t i ate_coun t 

copy i ng 
copy 

copy__acl_ 

copy__names__ 

copy_seg__ 

cost saving features 
alm_abs 
fort ran_abs 
pi l_abs 

see absentee usage 
see archiving 

see limited service systems 

CPU usage 
ready 

see metering 
see time 
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crawl i n& out 

see error handl i ng 

creating directories 
createdi r 

hcs_$append_branchx 

creat i ng 1 i nks 
1 ink 

hcs_$append_l i nk 

creating processes 
enter_abs__request 
logi n 
logout 
new_proc 
see logging in 

creating segments 
bas i c_system 
copy 
create 
edm 
qedx 

hcs_$append_b ranch 
hcs_$append_ branchx 
hcs_$make_seg 

creator 

see author 

current length 
3.3 

see length of segments 

daemon 

cancel_daemon__request 

dpr int 

dpunch 

1 i st_daemon_requests 
see bulk I/O 

daemon_di r_di r 
3.1 

Dartmouth facilities 
7.2 
bas i c 
bas i c_run 
(cont i nued) 
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Dartmouth facilities 
(cont i nued) 
bas i c_system 
pr i nt_dartmouth_l ibrary 
set_dartmouth_l ibrary 
v5bas i c 

data control word 
h.2 

data conversion 
see conversion 

data representation 
k.2 
5.3 
S.k 
8. it 



date and time operations 
1.13 

date conversion 
see conversion 

dates 
2.6 
3.3 

date (Active Function) 
date_t ime (Active Function) 
day (Active Function) 
day_name (Active Function) 
long_date (Active Function) 
month (Active Function) 
month_name (Active Function) 
year (Active Function) 
c!ock_ 

convert_date_to_bi nary_ 
date_t ime_ 
decode_clock__val ue_ 

DCW 

see data control word 

debugging tools 

change_er ror_mode 
compare 
compare_asc i i 
debug 

(cont i nued ) 
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debugging tools 
(cont i nued) 
di spl ay_component__name 
dump__segment 
hold 
prof i 1 e 
progress 
repr i nt_error 
trace 

trace_stack 
stu__ 

decimal integers 

convert_bi nary_i nteger_ 
see conversion 

default error handling 
6.5 

change_e r ro r__mode 

repr i nt_error 

act i ve_f nc_err_ 

see process interruption 

default status messages 
com_e r r_ 

default working directory 
change_def au 1 t_wd i r 
change__wd i r 
pr i nt_def aul t_wd i r 
get__def aul t_wdi r_ 

deferred execution 
see absentee usage 

del et i ng 
de 1 e te 
delete_di r 
deleteforce 
termi nate 
unl i nk 
delete_ 

hcs_$de1_d i r_tree 
hcs_$delent ry_f i le 
hcs_$delentry_seg 
term__ 

see address reuse 
see cancel 1 i ng 
see canon i cal i zat ion 
see termination 
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de 1 imi ters 
4.2 

descr i ptors 

decode_descr i ptor__ 

desk calculators 
calc 
decam 

device interface modules 
see I/O system interface 

dial ing up 
1.2 

DIM 

see I/O system interface 

di rector i es 
3.1 
1 ist 

1 i stnames (list) 

listotals (list) 

wal k_subtree 

see creating directories 

see default working directory 

see deleting 

see directory entry names 

see home directory 

see 1 i brar i es 

see process directories 

see protection 

see root directory 

see storage quotas 

see storage system 

see working directory 

directory access modes 
delete_J acl_di r 
1 i st_i acl_di r 
set__i acl_di r 
cv_d i r_acl_ 
cv_di r_mode_ 
hcs_$add_di r__acl_entr i es 
hcs_$del ete_di r_acl_entr i es 
hcs__$ 1 i st_di r_acl 
hcs_$replace_di r_acl 
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directory attributes 
3.3 

delete_iacl_di r 
delete_iacl_seg 
1 ist 

1 i st names (list) 
listotals (list) 
1 i s t_i acl_di r 
1 i st__i acl_seg 
set_j acl_di r 
set_iacl__seg 
status 

hcs_$add_acl_entr i es 

hcs_$add_di r_acl_entr i es 

hcs„$del ete_acl_ent r i es 

hcs_$delete__di r_acl_entr i es 

hcs_$l i st_acl 

hcs_$ 1 i s t_d i r_ac 1 

hcs_$ repl ace_acl 

hcs_$replace_di r__acl 

hcs_$star_ 

hcs_$status_ 

see protection 

directory creation 

see creating directories 

directory deletion 
see deleting 

directory entries 
see directories 
see 1 i nks 
see segments 

directory entry names 
addname 
del etename 

entry (Active Function) 
f s_chname 
1 ist 

1 i stnames (list) 

listotals (list) 

names 

rename 

status 

strip_entry (Active Function) 
suffix (Active Function) 
where 

(continued) 
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directory entry names 
(cont inued) 
check_s ta r_name__ 
get_equal_name_ 
hcs_$chname_f i le 
hcs_$chname__seg 
hcs_$f s_ get_path_name 
hcs_$star_ 

hcs_$status_ 
match_star_name_ 
suf f i xed__name__ 
see path names 
. see unique names 

directory hierarchy 
Section 3 
3.5 
copy 
1 ink 
move 
status 
unl i nk 

wal k_subtree 

copy_acl_ 

copy_names_ 

see storage system 

d i rectory names 

see default working directory 
see directory entry names 
see home directory 
see process directories 
see working directory 

directory renaming 

see directory entry names 

directory restructuring 
move 

hcs__$f s_move__f i le 
h c s_$ f s_mo v e_s eg 

discarding output 
di scard_putput_ 

disconnected processes 
see absentee usage 
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disconnections 

see logging out 

display terminals 
k.5 

see graphics 
see terminals 

diverting output 
consol e_output 
f i le_output 
iocall 

di scard_output_ 
see I/O streams 

dope 

see descriptors 

dumping segments 
dump_segment 

dynami c 1 i nki ng 
3.2 
term__ 

see address reuse 
see linkage sections 
see 1 i nki ng 
see searching 
see termination 

e (enter) 

see logging in 

EBCDIC 
5.2 

edi t i ng 

bas i c_system 

edm 

qedx 

efficiency 

see metering 

element size 
k.2 

emergency logout 
see logging out 
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encodi ng 
code 

enc i pher_ 

end of file 

see bit counts 

enter 

see logging in 

enterp 

see logging in 

entries 

see di rector i es 
see 1 i nks 
see segments 

entry names 

see directory entry names 
see entry point names 

entry point data 
5. 4 

entry point names 
pr i nt_l i nk_i nf o 
hcs__$make__pt r 
see 1 i nki ng 

entry points 
5.1* 

see i nterprocedure communication 
see 1 i nking 

EOF 

see end of file 

ep (enterp) 

see logging in 

EPL (obsolete) 

see PL/ I language 

eplbsa (obsolete) 
see aim 

equal convention 
check_star__name_ 
(conti nued) 
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equal convention 
(cont i nued) 
get_equa l_name_ 
match_s tar_name_ 

equals convention 
1.5 

erase characters 
1.3 

eras i ng 
1.3 

see canonical izat ion 
see deleting 

error codes 

see status codes 

error handl i ng 
Section 6 
6.1 
6.2 

change^ er ror_mode 

repr i nt_error 

act i ve_f nc_er r__ 

com_err_ 

comma n d_q u e r y_ 

cond i t ion_ 

f i nd_cond i t ion„info_ 

revers i on_ 

s i gnal_ 

see debugging tools 
see help 

error messages 

see status messages 

error recovery 
6.3 
hold 

program_i nterrupt 
re 1 ease 

see cleanup tools 

see debugging tools 

see process interruption 

error tables 

see status tables 



er ror_ou tput 

see I/O streams 

er ror_tab 1 e_ 

see status codes 

escape conventions 
1.3 
5.2 

exec_.com 

see active functions 

existence checking 

exists (Active Function) 

expanded command line 

see command processing 

expression evaluators 
ca 1 c 

see desk calculators 

external data 
5.4 

external symbols 
pr i nt_l i nk_i nfo 
make_obj ect_map_ 
see i nterprocedure communication 
see 1 inking 

f au 1 ts 
6.1 
6.5 

see condi t ions 

file I/O 
f i le_ 

file ma r k 

see bit counts 
see magnetic tapes 

file system 

see storage system 



I ndex 



Page 1** 

f i i es 
5.3 
f ile_ 
see I/O 
see segments 

fixed point data 
5.4 

floating point data 
5.1* 

formats 
5.5 

formatted I/O 
4.1 
4.3 
i oa_ 

see conversion 

formatted input 
read_J i st__ 

formatted output 
runoff 
runof f_abs 
ioa_ 

wr i te_l i st_ 

formatting character strings 

format__line (Active Function) 
string (Active Function) 

FORTRAN 
7.2 

close_f i le 

fortran 

f ortran_abs 

free storage 

see storage management 

f unct ions 

see active functions 
see procedures 

gates 

see protection 
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generat i ng cal 1 s 
cu_ 

hcs__$make_ptr 

see pointer generation 

generating pointers 

see pointer generation 

graphic characters 
see character codes 

graphic terminals 

see display terminals 
see terminals 

graph i cs 
4.1 
4.5 
plot_ 

see display terminals 

handling of unusual occurrences 
Section 6 
6.1 

hardware registers 
.debug 

he! p 
hel p 

peruse_text 

hi erarchy 

see directories 

hierarchy searching 
see searching 

hold 

see error recovery 

see process interruption 

home directory 

home_dir (Active Function) 

set_search_rules 

user (Active Function) 

user_inf o_ 

see default working directory 
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I/O 

Section 4 

i ocal 1 

print 

ioa__ 

ios_ 

tape_ 

see conversion 
see formatted I/O 

I/O (bulk) 

see bulk I/O 

I/O attachments 
4.2 

pr i nt_attach_tabl e 

I/O calls 
4.3 
ios_ 

I/O cleanup 
close_f i 1 e 
see cleanup tools 

I/O commands 

console_output 

dpr int 

dpunch 

f i 1 e_output 

iocal 1 

iomode 

1 i ne_length 

I/O daemon 
see daemon 

I/O errors 

see I/O status 

I/O facilities 
4.1 

I/O modes 
4.2 
iocal 1 
iomode 
ios_ 
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I/O status 
4.2 
ios_ 

I/O streams 
4.2 
iocal 1 
iomode 
ios_ 
syn 

see stream names 

I/O switch 
h.2 
4.6 
ios_ 
syn 

I/O system flowchart 
4.2 

I/O system interface 
4.2 
4.3 
4.6 
iocal 1 
iomode 
1 ine_length 
pr int_attach__tabl e 
broadcas t_ 
f i le_ 
ios_ 
syn 
tw_ 

see I0SIM 

IBM 1050 

see terminals 

IBM 2741 

see terminals 

i nclude f i les 
2.2 
3.2 

Pll 

i nf ormat i on 

check_i nf o_segs 
(continued) 
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i nf ormat ion 

(cont i nued) 
hel p 

make_peruse_text 

peruse__text 

who 

see metering 
see status 

initial access control list 
del ete_J acl_di r 
del ete__i acl_seg 
1 i st_i acl__d i r 
1 i st_i acl_seg 
set_i acl_di r 
set_i acl_seg 
see protection 

initial access control lists 
3.3 

initial ACL 

see initial access control li 



interaction tools 
answer 

program_i nterrupt 
command_query_ 
see debugging tools 
see interactive I/O 

interactive I/O 
ioa_ 

read_J i st_ 
wr i te_l i st_ 

intermediate interface modules 
see I/O system interface 

i nterprocedure communication 
see 1 i nki ng 

i nterrupts 
6.5 
8.5 

program_i nterrupt 

see process interruption 



initialized segments 
set_search__rules 
see Known Segment Table 

i n i t i at ion 
ini tiate 
where 

hcs_$ ini t i ate 
hcs_$ ini t i ate_count 
hcs_$make_p t r 
hcs_$make_seg 
see dynamic linking 
see 1 inking 

i nput 
ios_ 

read_l i st_ 
see I/O 

input conversion 

see formatted I/O 

integer representation 

convert_b i nary__i nteger_ 



intersegment linking 
pr i nt_l i nk_i nfo 
ma k e_o b j e c t _ma p_ 
see dynamic linking 
see 1 i nki ng 

interuser communication 
ma i 1 

IOSIM 
nstd_ 
tape__ 

see I/O system interface 
see synonyms 

I OS IM example 
it. 6 

i terat ion 

index_set (Active Function) 

Job Control Language 

see command processing 
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jobs 

see absentee usage 
see processes 

keypunches 

1,3 

kill characters 
1.3 

kill ing 

see cancel 1 i ng 

Known Segment Table (KST) 
3.1 

KST 

see Known Segment Table 

1 (login) 

see logging in 

label data 
5.4 

languages 
2.2 
7.2 
aim 
apl 
bas i c 
bi nd 
cal c 
debug 
decam 
edm 

exec_com 
fortran 
1 i sp 

1 • s p_comp i 1 e r 

Pll 

qedx 

runoff 

runof f__abs 

v5bas ic 



length of segment 
truncate 

length of segments 
adjust__bi t__count 
1 1 st 

1 istnames ( 1 ist) 
listotals (list) 
set_bi t_count 
status 

adjust_bi t_count_ 
decode_ob j ec t_ 
hcs__$ i n i t i ate_count 
hcs_$set__bc 
hcs_$star_ 
hcs__$status_ 
hcs__$ truncate_f ? le 
hcs_$ truncate_seg 
see bit counts 

1 ibrar ies 
3.1 
3.2 
8.2 

pr i nt_dartmouth__l ibrary 
pr i nt_search__rul es 
set_dartmouth_l ibrary 
set_search_di rs 
set_search_rules 

limited service systems 
7.1 
7.2 

1 i nk att r i butes 
3.3 
1 ist 

1 i stnames (list) 
1 istotals (1 ist) 
status 
hcs_$star_ 
hcs_$status_ 

1 i nk creat ion 

see creat i ng 1 i nks 



length of arguments 
cu_ 



1 i nk del et ion 
see deleting 
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] ink names 

see directory entry names 

link renaming 

see directory entry names 

1 i nk resol ut i on 
hcs_$status_ 



Linkage Offset 
see dynamic 
see 1 inki ng 



Table (LOT) 
1 inking 



1 inkage sections 
pr int_l i nk_i nf o 
ma k e_p b j e c t_jna p__ 
see 1 i nki ng 

1 i nki ng 
3.2 
bind 
1 ink 

pr i nt_search_rul es 

set_search_di rs 

set_search_.ru 1 es 

term! nate 

unl i nk 

delete.. 

hcs_$make_pt r 

see binding 

see creat i ng 1 i nks 

see dynamic linking 

1 i nks 

see 1 i nki ng 

LISP 
7.2 
1 i sp 

1 « s p__comp i 1 e r 

1 i stener 
1.3 
cu_ 

1 i st i ng 
1 ist 

1 i stnames (list) 
1 i stotal s (1 ist) 
(cont i nued) 



1 ? st i ng 

(cont i nued ) 
pr i nt 
see I/O 

see storage system 

loading 

see binding 
see 1 inki ng 

logging in 
1.2 
enter 
logi n 

logging out 
1.2 

logout 

logical operations 
1.9 

and (Active Function) 
not (Active Function) 
or (Active Function) 

1 ogi n 

see logging in 

login directory 

see default working directory 
see logging in 

login responder 

user (Active Function) 
user_i nf o__ 

login time 

user (Active Function) 
user_i nfo_ 

login word 

user (Active Function) 
user_ i nf o_ 

logon 

see logging in 

logout 
logout 

see logging out 
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LOT 

see Linkage Offset Table 

machine conditions 
debug 

traee__stack 

machine languages 
8.5 
aim 
debug 

macros 
1.8 
1.9 
1.10 
1.11 
1.12 
1.13 
1.1k 
1.15 
abbrev 
do 

exec_com 
qedx 

see active functions 
see command processing 

magnetic tapes 
5.5 
8.1* 
nstd_ 
tape__ 

mai 1 

see interuser communication 

mail box checking 
mai 1 

main program 

see procedures 

see programming environment 

making known 

see initiation 

making unknown 

see termination 
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maps 

pr i nt_b i nd_map 
make_obj ect_map_ 

maximum length 
3.3 



maximum line length 
1 i r.e_l ength 



mcc 

see punched cards 

mcc cards 
k.k 

message of the day 
pr int_motd 



messages 
see I/O 

see status messages 

meter i ng 
2.6 

page_trace 

print_l inkage_usage 

prof i le 

progress 

resource_usage 

cpu_t i me__and_pag i ng_ 

hcs_$status_ 

time r__manager_ 

tota l_cpu_t i me_ 

MIX 

7.2 



modes 
3.1* 
k.2 

see protection 
see status 

modifying segments 
debug 

moni tor i ng 

see metering 



I ndex 



Page 20 

moving names 
move_names_ 

see directory entry names 

moving quotas 

see storage quotas 

moving segments 
move 

hcs_$f s__move__ f i 1 e 
h c s_$ f s__mo v e_s e g 

Multics card code 

5.2 

see punched cards 

multiple device I/O 
see broadcasting 

multiple names 

see directory entry names 

multisegment files 
3.5 

see I/O 

name copying 
copy_names_ 

see directory entry names 

name space 

see address space 

names 
1.5 

see address space 

see directory entry names 

see path names 

nami ng 

see directory entry names 

naming conventions 
1.5 
8.1 

see directory entry names 
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nonlocal gotos 
6.3 

notes 
memo 

number conversion 
see conversion 

object segments 
5.5 
bind 

pr int_bi nd_map 
decode_object__ 
make__obj ect_map_ 
see linkage sections 

obsolete procedures 
8.3 

octal dumping of segments 
debug 

dump_segmen t 

octal integers 
aim 
debug 
decam 

convert_bi nary_integer. 

cv_oct_ 

see conversion 

of f 1 i ne 

see bulk I/O 

offset data 
5.1* 

offset names 
1.5 

decode_entryname__ 

opening f i les 

see initiation 

output 
k.h 

dpr i nt 
dpunch 

(cont i nued) 
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output 

(cont i nued ) 
f i 1 e_output 
pr i nt 

di scard__output_ 
! os_ 

wr i te_J i st_ 
see I/O 

output conversion 
see formatted I/O 

output line length 

see terminal line length 

P 

see interprocess communication 

packi ng 

see archiving 
see binding 

page faults 
page_trace 

pages used 

see metering 
see records used 

paging 

see storage system 

parameters 

see argument lists 

parentheses 

see command language 

par i ty 
8.5 

pars ing 

parse__f i le__ 

passwords 

see logging in 

path names 
1.5 

(cont i nued) 
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path names 

(cont i nued) 
3.1 

directory (Active Function) 
get_pathname (Active Function) 
home_dir (Active Function) 
i ni t i ate 
1 ist 

listnames (list) 

1 i stotal s (list) 

1 i st_ref__names 

path (Active Function) 

pd (Active Function) 

pr int__defaul t__wdi r 

pr i nt__wdi r 

strip (Active Function) 
wd (Active Function) 
where 

check__s tar__name_ 
decode_ent ryname_ 
expand__path_ 
get__equa 1 __name_ 
ge t_pd i r_ 
get__wdi r_ 

hcs_$ f s get path name 
hcs_$ initiate 
hcs_$ i n i t i ate__count 
hcs_$make_seg 
hcs_$star_ 
hcs_$status_ 
hcs_$ truncate_.fi 1 e 
mate h__s t a r __n ame_ 
suf f i xed__name__ 
see 1 i nki ng 

permi t list 

see protection 

PL/ I 

close_f i le 

PL/ I language 
Pll 

pi l_abs 

pointer conversion 

hcs__$f s__get ..path, name 
he s__$ f s_ge t _r e f_n ame 
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pointer data 



Process Initialization Table (PI 
3.1 



pointer generation 
cu_ 

hcs__$fs get see ptr 
hcs_$ i ni t iate 
hcs_$ i n i t i ate__count 
hcs_$make_ptr 
hcs_$make_seg 

pr i nter 

see bulk I/O 

pr i nt i ng 
k.l 
h.k 

dpr i nt 

dump__segment 
pr i nt 

procdef 

see command processing 

procedures 
2.1 

process creation 

see creating processes 

process data segment 
3.1 

process directories 
3.1 

pd (Active Function) 
set_search_rul es 
get_pd i r__ 
hcs__$make_seg 

process groups 
get_group_id_ 

process identifiers 
get_process_i d_ 

process information 

user (Active Function) 
user_i nf o_ 
see metering 



process interruption 
6.2 
hold 

program_i nterrupt 

rel ease 

start 

t imer_manager__ 
see conditions 

process termination 
logout 
new_proc 
see logging out 

processed i r_di r 
3.1 

processes 
new__proc 

see absentee usage 
see logging in 
see logging out 

program interruption 

see process interruption 

program_i nterrupt 

see process interruption 

programming environment 
Section 2 

programming languages 
see languages 

programming standards 
2.5 



programming style 
2.5 

project names 
1.1 

user (Active Function) 
who 

user_i nf o_ 
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protect ! on 
3. if 

delete_i acl_di r 
del ete_iacl_seg 
deleteacl 

de 1 etecac 1 (deleteacl) 
1 i st_J acl_di r 
1 i st__i acl_seg 
1 i stacl 

1 i stcacl ( 1 i stacl ) 
set_i acl_di r 
set_i acl_seg 
setacl 

setcacl (setacl) 

copy_acl__ 

cv_ac 1_ 

cv_di r_a c 1 _ 

cv_d i r__mode__ 

cv_jnode_ 

cv_user i d_ 

hcs_$add_acl_entr i es 

hcs_$add_d i r___acl_entr i es 

hcs__$delete__ad_entr i es 

hcs__$del ete_d i r_acl__entr ies 

h c s_$ f s_ge t_mo de 

hcs_$ 1 i s t_a c 1 

hcs_$ 1 i s t_d i r_acl 

hcs_$ repl ace_acl 

hcs_$ replace_d i r_acl 

see access control list 

pseudo-devi ce 
h.2 

punched cards 
if.l 
k.k 
5.2 

dpunch 

see bulk I/O 
qui ts 

see process interruption 

qui tt ing 

see process interruption 

quotas 

resource_usage 
see storage quotas 
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quoted strings 

see command language 

radix conversion 
decam 

see conversion 

random number generators 
random^ 

raw 

see punched cards 

read-ahead 
h.2 
i os_ 

reading cards 
k.l 

see bulk I/O 

see punched cards 

ready messages 
1.2 
ready 
ready_of f 
ready__on 
cu_ 

real data 
5.1* 

record quotas 

see storage quotas 

redirecting output 
consol e_output 
f i 1 e_ou tpu t 
see I/O streams 
see output 

reference names 
1.5 

get_pathname (Active Function) 

i ni t iate 

1 i st_ref_names 

where 

decode_ent ryname_ 
expand_path_ 
(cont i nued) 
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reference names 
(cont i nued) 
hcs_$f s__get_ref__name 
hcs $f s_get_seg_.pt r 
hcs_$ i ni t i ate 
hcs_$ i n i t i ate_count 
hcs_$make_pt r 
hcs_$make_seg 
hcs_$ termi nate_f i le 
hcs_$ termi nate_name 
hcs_$ termi nate__noname 
hcs_$termi nate_seg 
term_ 

referencing__di r 

set_search__rules 

rel_l ink 

see binding 

rel__symbol 

see binding 

rel_text 

see binding 

relative path names 
expand__path__ 
see path names 

relative segments 
see termination 

release 

see error recovery 

see process interruption 

remi nders 
memo 

remote devices 
see terminals 

removing segments 
see deleting 
see termination 

renami ng 

see directory entry names 
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reserved characters 
5.2 

see command language 

reserved names 
6.5 
8.1 
8.2 

reserved segment numbers 
hcs__$ i n i t i ate 
hcs__$ termi nate_f i le 
hcs_$termi nate__seg 

resource 1 imi ts 
resource_usage 
see accounting 
see metering 
see storage quotas 

resource usage 
resource_usage 

restart i ng 
start 

retrieval 
3.5 

ring brackets 

see protection 

rings 

see protection 

root directory 
3.1 

runt ime 

see programming environment 

runtime storage management 
see storage management 

safety switch 
3.3 

saf ety__sw_of f 
saf ety_sw__on 
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scratch segments 

see temporary segments 

SDB 

see Stream Data Block 

search rules 
3.2 

change_def au 1 t_wd i r 
change_wdi r 
pr i nt_def aul t_wdi r 
pr i nt_wdi r 
set_search_di rs 
set_search_rules 
where 

change_wd i r_ 
get_wd i r_ 
hcs__$make_ptr 
see default working directory 
see working directory 

search i ng 

h c s__$ f s_g e t__p a t h_n ame 

hcs__$make_ptr 

see dynamic linking 

see search rules 

secondary storage device 
3.3 

segment access modes 
del ete__i acl__seg 
1 i st_i acl_seg 
set_i ac l_seg 
cv__acl_ 
cv_mode_ 

hcs__$add_acl_entr i es 
hcs_$delete_ac gentries 
hcs_$ 1 i st_acl 
hcs_$repl ace_acl 

segment addressing 

see pointer generation 

segment attributes 
3.3 

del eteacl 
1 i st 

1 i stnames (1 i s t ) 
(cont i nued) 
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segment attributes 
(cont i nued) 
1 i stotal s (list) 
1 i stacl 

saf ety_sw__of f 

saf ety_sw_on 

setacl 

status 

hcs_$set_bc 

hcs_$set__bc_seg 

hcs__$star_ 

hcs_$status_ 

see length of segments 

see protection 

segment copying 
see copying 

segment creation 

see creating segments 

segment deletion 
see deleting 

segment formats 
5.5 

segment formatting 
i ndent 

make_peruse_text 

segment initiation 
see initiation 

segment length 

see length of segments 

segment name operations 
1.12 

pd (Active Function) 

segment names 
1.5 
8.1 

see directory entry names 

segment numbers 
1 i st_ref names 
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segment packing 
see archiving 
see binding 

segment referencing 
see initiation 
see 1 i nk i ng 

see pointer generation 

segment renaming 

see directory entry names 

segment termination 
see termination 

segment truncation 
see truncation 

segments 
5.3 

see creating segments 
see deleting 

see directory entry names 

see i n i t i a t ion 

see length of segments 

see protection 

see storage system 

see temporary segments 

see termination 

semaphores 

see interprocess communication 

setting bit counts 
see bit counts 

seven-punch cards 
dpunch 

see punched cards 

shriek names 

see unique strings 

s i gnal s 

see conditions 

s imulat ion 
random 
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si eepi ng 

t i mer_manager_ 

snapping 1 inks 

see dynamic linking 

sor t i ng 

arch i ve_sor t 
reorder_arch i ve 
sort_f i le 

space saving 

see archiving 
see binding 

special characters 
1.3 

see character codes 

special sessions 
see logging in 

special subsystems 
Section 7 

spec i f i ers 

see descriptors 

spool i ng 

see bulk I/O 

stack frame pointer 
cu_ 

stack frames 
debug 

trace_stack 

stack referencing 
debug 

trace_stack 
cu_ 

stack segment 
3.1 

stacks 

see stack frames 
see stack segments 
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Standard Data Formats and Codes 
Section 5 

standard tape formats 
see magnetic tapes 

standards 
2.5 

star convention 
1.5 

f s__chname 
c h e c k_s t a r_n ame__ 
ge t_e q u a 1 _n ame__ 
hcs_$star_ 
ma t c h_s t a r_n a me_ 

start 

see error recovery 
see process interruption 

start up 
1.2 

exec_com 
see logging in 

start_up.ec 

see start up 

stat i c 1 i nki ng 

see binding 

see linkage sections 

see 1 i nki ng 

static storage 
new_proc 

see storage management 

status 

check_J nf o_segs 
hel p 

how_many_users 
1 ist 

1 i stnames (list) 
listotals (list) 
1 i st_abs_requests 
1 i s t_daemon_requests 
peruse_text 
status 

(cont i nued) 



status 

(cont i nued ) 
who 

hcs_$star_ 
hcs_$status_ 
see I/O status 

status codes 
k.2 
6.1 
6.1* 

com_e r r_ 

u n pa c k__s y s t em_cod e__ 

see I/O system interface 

status formats 
k.2 

status messages 
6.1* 

repr i nt_er ror 
act i ve_f nc_e rr__ 
com__er r_ 
command__query_ 

status tables 
6.4 

storage allocation 

see storage management 

storage hierarchy 
see directories 
see storage system 

storage management 
see address reuse 
see archiving 
see deleting 
see directories 
see I/O 

see length of segments 

see segments 

see storage quotas 

storage quotas 
getquota 
movequota 
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storage system 
Section 3 
k.2 

see directory hierarchy 

storage system I/O 
i*. 3 

consol e_output 
f i 1 e_output 

Stream Data Block (SDB) 

see I/O system interface 

stream names 
1.5 
8.1 

streams 

see I/O streams 

structure data 
5.k 

subrout i nes 
2.1 

Section 10 
see procedures 

subsystems 
1.2 

Section 7 
7.2 

see languages 

suf f i xes 
8.1 

strip (Active Function) 
strip_entry (Active Function) 
suffix (Active Function) 
suf f i xed_name__ 

symbol tables 
stu_ 

symbolic debugging 
debug 
stu_ 

see debugging tools 



synchron i zat ? on 
k.2 
ios_ 

see interprocess communication 

synonyms 
syn 

see directory entry names 
see I/O system interface 

syntax analysis 
parse_f i 1 e_ 

system 1 i brar ies 
3.1 

see 1 i brar i es 
see search rules 

system load 

how_ma n y__u s e r s 
who 

system status 
help 

how_ma n y__u s e r s 

1 i st_abs__reques ts 

page_trace 

peruse_text 

pr i nt_motd 

who 

system_cont rol_d i r 
3.1 



system_l i brary_auth_ma i nt 
3.1 



system_l i brary_standard 
3.1 

tapes 

see magnetic tapes 

teletype model 33,35,37,38 
see terminals 

temporary files 

see temporary segments 
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temporary segments 
hcs_$make_seg 
un i que__chars_ 
see process directories 
see storage management 
see unique names 

temporary storage 

see process directories 
see storage management 
see temporary segments 

terminal line length 
1 i ne_length 

terminal s 
1.2 
1.3 
4.1 

consol e__putput 

1 i ne_J ength 

set_com__ 1 ine 

user (Active Function) 

read_l i st__ 

tw_ 

user_J nfo_ 
wr i te_J i st__ 
see I/O 

terminating processes 

see process termination 

termi nation 
logout 
new_proc 
termi nate 

hcs_$ termi nate__f i le 
hcs_$ termi nate_jiame 
hcs__$termi nate_noname 
hcs_$ termi nate__seg 
term__ 

see cancel 1 i ng 

see process termination 

text editing 
see editing 

text formatting 
runoff 
runoff abs 



text scanning 
compare_asci i 
parse_f i le_ 

text sorting 
see sorting 



t ime 
2 



6 

date_time (Active Function) 
hour (Active Function) 
minute (Active Function) 
time (Active Function) 
c lock__ 

convert_date_to_b? nary_ 
date__t i me_ 
decode_clock_val ue__ 
t imer_manager__ 
see metering 



transfer vector 
i*. 6 

translators 

see languages 

traps 

see faults 

truncat ion 
truncate 

hcs_$truncate_f i le 
hcs__$ truncate_seg 

type conversion 
see conversion 

typing conventions 
1.3 

abbrev 

see canon i cal i zat i on 



udd 

see user_d i r_di r 

unique identifiers 
3.3 
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unique names 

hcs_$make__seg 

unique strings 

unique (Active Function) 
unique_bi ts_ 
unique_chars_ 

unl i nki ng 
unl i nk 
delete., 
see deleting 
see termination 

unsnappi ng 

termi nate_ref name (terminate) 
termi nate_segno (terminate) 
termi nate_s i ngl e_ref name 

( termi nate 

term_ 

see termination 

unsnappi ng 1 i nks 
see termination 

unwi nd i ng 
6.3 

usage data 

user (Active Function) 
user_i nf o__ 
see metering 

usage measures 
see metering 

useless output 

program_J nterrupt 
di scard_output_ 

user names 
1.1 
3.k 

user (Active Function) 
who 

cv_user i d_ 
user__ i nfo_ 

user parameters 
1.15 

user (Active Function) 
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user weight 

user (Active Function) 
user__i nfo_ 

user_di r_di r 
3.1 

user_i /o 

see I/O streams 
see terminals 

user_i nput 

see I/O streams 

user__outpu t 

see I/O streams 

users 

how_many_users 
who 

V 

see interprocess communication 

val i dat ion 1 evel 
cu_ 

see protection 

variable length argument list 
cu_ 

varying string data 
5.1* 

VI I -punch cards 

see seven-punch cards 

virtual memory 

see directory hierarchy 
see storage system 

wa i t i ng 
2.6 

timer_manager_ 

wakeups 
2.6 

t imer_manager_ 
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wd ! r 

see working directory 

working directory 
change_wdi r 
pr i nt_search__ru 1 es 
pr intjwdi r 
set_search_ru les 
wal k__subt ree 
wd (Active Function) 
change__wdi r_ 
expand_path_ 
ge t_wd i r_ 

see default working directory 



working set 
page_trace 

workspace 
i*. 2 
ios_ 

wr i te-beh i nd 

i os_ 



writing to multiple I/O streams 
see broadcasting 



